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Abstract 

We present version 3.4 of the CalcHEP software package which is designed for effective evaluation 
and simulation of high energy physics collider processes at parton level. 

The main features of CalcHEP are the computation of Feynman diagrams, integration over multi- 
particle phase space and event simulation at parton level. The principle attractive key-points along 
these lines are that it has: a) an easy startup even for those who are not familiar with CalcHEP; b) 
a friendly and convenient graphical user interface (GUI); c) the option for a user to easily modify 
a model or introduce a new model by either using the graphical interface or by using an external 
package with the possibility of cross checking the results in different gauges; d) a batch interface 
which allows to perform very complicated and tedious calculations connecting production and decay 
modes for processes with many particles in the final state. 

With this features set, CalcHEP can efficiently perform calculations with a high level of automa- 
tion from a theory in the form of a Lagrangian down to phenomenology in the form of cross sections, 
parton level event simulation and various kinematical distributions. 

In this paper we report on the new features of CalcHEP 3.4 which improves the power of our 
package to be an effective tool for the study of modern collider phenomenology. 
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1. Introduction 



CalcHEP (Calculations in High Energy Physics) is a package for the automatic evaluation 
of production cross sections and decay widths in elementary particle physics at the lowest order of 
perturbation theory (i.e. in the born approximation) within various theoretical models of particle 
physics including effective models. 

CalcHEP is the next step in the development of the CompHEP[lj package which was cre- 
ated by one of us (AP) together with his colleagues from the Skobeltsyn Institute of Nuclear 
Physics. The main idea of CalcHEP is to provide an interactive environment where the user 
can pass from the Lagrangian to the final distributions effectively with a high level of automation. 
Other packages created to solve similar problems are 

FeynArts/FormCalcQ S, Q, MADGRAPH^, [III, HELAC-PHEGAS0, Jli, Q, O'MEGAllij, 
WHIZARDdil, and SHERPAQ [i8|. Since the last published version 2.3 [ij, CalcHEP has been 



significantly improved to become an efficient and powerful tool for modern collider physics studies. 

One of the main advantages of CalcHEP is a convenient interactive menu-driven Graphical User 
Interface (GUI) with detailed contextual help which can be viewed by pressing the Fl key. Also, the 
notations used in CalcHEP are very similar to those used in particles physics. These features, and 
others, allow a beginner to start using CalcHEP right away even if he/she has no prior experience 
with CalcHEP. 

Among the other important advantages of CalcHEP are: the ability to create and/or modify 
models using either the internal graphical editor or by using external editors/packages, the option 
to use either Feynman or unitary gauge in the evaluation of Feynman diagrams which provides a 
powerful cross check of the model implementation and the numerical results, the ability to dynam- 
ically and automatically calculate the width of unstable particles when the parameters of a model 
are changed, and the ability to easily choose Feynman diagrams and squared Feynman diagrams to 
remove from the calculation for a study of interference effects (for example). 

The CalcHEP package consists of two modules: a symbolic and a numerical module. The symbolic 
session allows the user to dynamically work with a physics model, symbolically calculate squared 
matrix elements, export the results as C-code and compile the C-code into the executable n_calchep. 
The numerical module performs the evaluation of the integral over phase space to determine the 
cross section or decay width of the user-defined process. It can also histogram the events to produce 
various kinematical distributions taking into account user-defined kinematical cuts. Additionally, 
CalcHEP can be run in non-interactive mode using various scripts provided for the user including 
the batch interface summarized below. 

Among the new important features is a batch interface, which takes the user's input and autom- 
atizes the calculation of the production and decay processes and combines the results, connecting 
production processes with decays, to produce a final event file in Les Houches Event (LHE) format. 
The final LHE file can be used in other Monte Carlo (MC) software, including the MC software 
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of the LHC experiments. The batch interface also supports scanning over multiple parameters and 
parallelizes the entire calculation over the processors of a multi-core machine or over the processors of 
a high performance computing cluster which enables the use of hundreds or thousands of processors 
for the calculation. This last feature is responsible for a significant enhancement in the speed of the 
symbolic and numerical calculations. 

The flexibility of CalcHEP allows to work with a variety of Models Beyond the Standard Model 
(BSM). While the Standard Model is included in the CalcHEP distribution, various BSM models, for 



example, the SUSY Models MSSM, NMSSM, CPVMSSM |20|, |21 
Leptoquarks 



2M, Little Higgs Model [25 



22l . |23[, the complete model with 



261 , MUED model [27[ and many 



TechniColor Model 

others in the CalcHEP format are available to be downloaded, imported and used by CalcHEP. 
The complete set of model for CalcHEP is available at the High Energy Physics Model Database 
(HEPMDB) Q described in section [931 and listed in TableEl 

For SUSY models there are external programs Isajet, SuSpect, SoftSusy 
NMSSMTools 3l|, CPsuperH 32| for spectra calculation at loop level. An interface with these 



2i, SPheno 



programs is implemented for the SUSY models mentioned above and can be easily realized via the 
SLHAplus package 33|] included in CalcHEP for any BSM model. 

There are two public codes intended for the generation of CalcHEP format model files using, as 
input, a short model definition in terms of field multiplets, model parameters, and a Lagrangian. 



They are LanHEP [3J] and FeynRules [35| . Most of the CalcHEP models were generated by LanHEP. 



CalcHEP can be used as a generator of matrix elements for external programs. This option was 



realized in the micrOMEGAs (361 . 1371 ] package for calculation of Dark Matter observables. Develop- 



ment of CalcHEP was strongly influenced by the development of micrOMEGAs. 

This paper has the following structure: In Section [21 we briefly describe the steps to install 
CalcHEP. In Sections [3] and [4] we discuss the interactive symbolic and numerical sessions of CalcHEP, 
respectively. In Section [5l we describe how to work with the results of the numerical session. In 
Sections [Sand [71 we introduce the new features of non-interactive sessions together with the new batch 
interface. In Section [H] we present the models of new physics which are implemented in CalcHEP and 
discuss the core methods for implementing new models. In Section [9l we describe some external tools 
for implementing new models and the HEPMDB repository for models. In Section [TOl we describe 
how to use the matrix element code from CalcHEP with external code. In Section [Til we describe 
some benchmarks for testing the CalcHEP installation. In Section [121 we conclude. 



2. Installation 

The CalcHEP source codes, a complete manual corresponding to the current version and a va- 
riety of Beyond the Standard Model (BSM) implementations for CalcHEP are presented on the 
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CalcHEP web site 0: 



http : / / theory . sinp . msu . ru/~pukhov/calchep . html. 

CalcHEP is designed to run on an assortment of UNIX platforms. The current version has been 
tested on Linux and Darwin. To install CalcHEP, the user should unpack the downloaded file 

tar -xvzf calchep_3.4.tgz 

This will create the directory calchep_3.4 which we refer to in this paper as $CALCHEP. To com- 
pile CalcHEP, the user should cd into the $CALCHEP directory and run 

gmake or make 

In case of success user should get a message in the end of compilation 

# CalcHEP has compiled successfuly and can be started. 
In case of a compilation problem, the user can try to find a solution in the CalcHEP manual or ask the 
authors for help by e-mail. Once the package is compiled, the user should create a working directory 
where the calculations will be performed. We will refer to this directory as $WORK throughout this 
paper. To install this directory, the user should be in the $CALCHEP directory and run: 

. /mkUsrDir $WORK 

This command creates the directory $WORK along with the subdirectories 

models/ tmp/ results/ bin/ , 

which are intended for the user's theoretical particle physics models, temporary files and numerical 
session files. $WORK also contains the scripts: 

./calchep and . /calchep_batch , 

which launch the CalcHEP GUI and batch sessions, respectively. 

By default only Standard model is distributed together with CalcHEP package. Other models 
have to be download independently. Large set of BSM can be downloaded directly from CalcHEP WEB 
page. More complete set of models is stored in repository 

http : / /hepmdb . soton . ac . uk/ 
which we present it in section 19.41 



^Another resource for BSM implementatfons for CalcHEP is HEPMDB which is described in Section [3] 
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3. Interactive GUI symbolic session 

The menu structure for the symbohc session of CalcHEP is shown schematically in Fig. [TJ These 
menus allow the user to: 

• select a model or import a new model from the file system [Menu 1] . 

• implement changes in a model [Menu 2,3] and check for syntax errors. 

• set a flag which forces a calculation to be performed in physical (unitary) gauge for a model 
which has been written in t'Hooft-Feynman gauge [Menu 2]; 

• check numerically the mass spectrum, dependent parameter values and particle decay modes 
before generating a process [Menu 4]; 

• enter a scattering or decay process by specifying incoming and outgoing particles where 1 — 
2, . . . , 1 — 7- 8 decay processes are and 2 — 2, . . . , 2 — )■ 7 scattering processes are supported 
[Menu 2,5]; 

• generate Feynman diagrams, display them, optionally exclude diagrams as well as create the 
corresponding I^T^X output [Menu 6]; 

• generate, display and optionally exclude squared Feynman diagrams as well as create the cor- 
responding I^T[t;X output [Menu 7]; 

• calculate analytic expressions for squared matrix elements by using the fast built-in symbolic 
calculator [Menu 7]; 

• export the symbolic expressions of the squared diagrams in REDUCE, MATHEMATICA or 
FORM format for further symbolic and/or numerical manipulations [Menu 7,8]; 

• generate optimized C code for the squared matrix element for further numerical calculations 
[Menu 8]; 

• launch the compilation of the generated C code and start the corresponding numerical session 
[Menu 8]; 



Many new features have been added to the symbolic session compared to version 2.3 [19|. They 



are: 



* CalcHEP supports collision processes with polarized massless fermions and vector bosons in 
the initial state. This is accomplished by ending the particle's name with a °L as in: 
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Menu 3 



Menu 1 



Parameters 
Constraints 



Particles 



Libraries 
RENAME 
CHECK MODEL 



Menu 4 



Parameters 



All Constraints 



Masses,Widths,Br 



Menu 8 



C-code(for num calc) \ 
C-compiler 
Edit linker 
REDUCE code 
MATHEMATICA code 
FORM code 
Enter new process 



SELECT MODEL 



IMPORT OF MODELS 



Menu 2 



Enter Process 



Force Unit gauge = OFF 



Edit Model 



Numerical Evaluations 




Delete model 



Menu 7 



View squared diagrams 



Symbolic calculation 



Make&Launch n calchep 



REDUCE program 



f 



Menu 9 



FILE SEARCH/LIST 



Menu 5 



Enter processes: p,p -> W+,2*x 
composite p consists of: u,U,d,D 
Exclude diagrams with: A 
Exclude X-particles: G 



w Menu 6 



View diagrams 



Square diagrams 



Write down processes 



Figure 1: A menu-tree for the symbolic session of CalcHEP 



el,kl->e,Z 



CalcHEP now supports particles with spin up to 2 (including s= 0, 1/2, 1, 3/2 and 2). 

A new column has been added to the particle table allowing to enter an ID for the particle 
from the Monte Carlo numbering scheme 381]. This ID is used to interface the model with 
parton structure functions, such as CTEQ and MRST, and with Monte Carlo packages such as 
PYTHIA 39|. In other words, this ID allows to interface a CalcHEP model with a package that 



uses the Monte Carlo ID and is independent of the names given to the particles. CalcHEP does 
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a basic sanity test on the Monte Carlo ID's given to particles to make sure they do not clash with 
the id's of existing mesons and baryons from the PDG. This helps avoid potential problems 
with hadronization and fragmentation when the CalcHEP events are being passed to external 
MC generators. 



* 



CalcHEP includes the SLHAplus package [33|] and its functions can be used in CalcHEP model 
constraints. It allows to 



* 



- use an SLHA interface [40|, |41|] for external packages which calculate particle spectrums, 
mixing matrices of particle multiplets and other model constraints. SLHAplus allows to 
organize the corresponding interface with minimal user programming; 

- implement tree level calculations for particle spectra and mixing matrices for any field 
multiplet; 

- include QCD Yukawa corrections for Higgs-q-q vertices for correct Higgs width calcula- 
tions; 

Further details can be found in Section 19.11 

In the current CalcHEP version, we have added calculations for the Higgs-7-7 and Higgs-gluon- 
gluon effective couplings to the SLHAplus routines. See section 19.21 for further details. 

* The width of a particle can now be calculated automatically during a numerical evaluation 
when the parameters change. To use this feature, the user must add a ! to the beginning of 
the width name in the particle table. For example, to activate automatic calculation of the 
Higgs boson's width, the user should specify this in the particle table in the following way 

Full name I A |A+ I PDG number |2*spin| mass I width |color|aux| 
Higgs |h |h 125 10 I Mh I !wh |1 I I 

The exclamation mark before the width symbol forces the width to be calculated automatically. 
CalcHEP does this by sequentially calculating the 1 — 2, 1 — 3, and 1 — j- 4 processes until a 
non-zero value for the width is obtained. However, in case of an important off-shell contribution 
at higher multiplicity, a proper matching is not yet realized. 

If the particle width is present in an SLHA file that is read by CalcHEP however, the automatic 
width calculation is not done. The width from the SLHA file is used in stead. In this way, the 
user can use the width calculated from an external program in a CalcHEP calculation by using 
the SLHAplus routines. We should note that this behavior can be fine tuned as SLHAplus has 
an option to read or discard the widths from an SLHA file. 
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* Although SLHAplus contains many useful functions for model implementation, we foresee the 
need to link external packages and user written code to CalcHEP. This can be done in the 
new model table Libraries [Menu 3] and greatly enhances the facilities of CalcHEP. The user 
simply enters the path to the compiled code to be linked when generating n_calchep. The 
Libraries table also allows the user to define prototypes of external functions. Two important 

structure function sets and user defined 



uses for this functionality is to link the LHAPDF 42 



functions for phase space cuts and histograms. See the details in Sections 14.51 and 18.51 

* The Numerical Evaluations menu [Menu 4] allows to evaluate the dependent parameters 
(constraints) as well as the widths and branching ratios of the particles before generating the 
code for a specific process. Like the automatic width calculation, it uses the dynamic linking 
facilities of modern operation systems. During this procedure, the decay processes are compiled 
when they are needed and stored in the directory $WORK/results/aux for subsequent usage 
until the model is changed. 



CalcHEP can generate libraries of matrix elements to use with other packages (see Section [10 



These tools were first developed for the micrOMEGAs package (361 . |37j to dynamically generate 
and link arbitrary matrix elements during runtime. 



4. Interactive GUI numerical session 

The menu system for the interactive numerical session GUI of CalcHEP is schematically presented 
in Fig. |2l It allows the user to: 

• select a subprocess for numerical processing if the generated code contains more than one; 

• set the momenta and helicities of incoming particles. The helicity is defined with respect to 
the direction of motion. For the electron it is in the interval [— |, |]. A positive value (e.g. |) 
corresponds to a right-handed electron [Menu 1,2]; 

• convolute the squared matrix element with structure functions and beam spectra. CalcHEP comes 
with a set of parton distribution functions for protons and anti-protons, initial state radiation 
and beamstrahlung spectra for electrons, and the laser photon spectrum, Weizsaecker- Williams 
photon structure functions and proton photon structure functions for the photon [Menu 3] . The 
user also has the option to use the LHAPDF structure functions (see Sections 14.11 and 18.51 for 
details). We note that the contents of this menu depend on the particle ID (see Section 18731) 
and not on the particle's name; 

• modify independent physical parameters such as the coupling constants and masses which are 
involved in the process [Menu 1] . These parameters can be changed one by one or the user can 
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read the parameter values from a file using this menu. The file must contain one parameter on 
each line of the file with the parameter name on the left and the numerical value on the right 
separated by whitespace. For example, 

Mh 125 

• view masses and dependent parameters (constraints) [Menu 1]. The list of dependent parame- 
ters which appear in this menu depends on whether they have been set to be "public" in the 
model files (see Section [8^ : 

• calculate and view particle widths and decay fractions. This can be done via the Constraints 
item of [Menu 1]. This menu also allows to write the full list of particle masses, widths and 
branching ratios to a file in SLHA format; 

• choose the scale used in the evaluation of the QCD coupling constant and parton structure 
functions [Menu 4]. We also provide the user the option to define the normalization and 
factorization scales independently. 

• apply various kinematical cuts [Menu 1 - Cuts option]; 

• define the kinematic scheme (phase space parametrization) in order to improve the efficiency 
of the Monte Carlo (MC) integration and also to introduce a phase space mapping in order to 
smooth the sharp peaks of a squared matrix element and structure functions [Menu 1 - Phase 
space mapping option]; 

• perform a Monte Carlo integration of the phase space by VEGAS [Menu 1,6] (see Section HTj); 

• generate partonic level events [Menu 1,6,7] (see Section 

• set and display distributions of various kinematical variables. It is also possible to export the 
distribution to file for use in external programs such as ETgX, gnuplot, PAW and Mathematica 
[Menu 6]; 



4.1. Built-in and LHAPDF parton distribution functions 

CalcHEP comes preinstalled with several parton distribution function sets These sets and tools 
for updating them have been described in [l9|. To use one of these built-in PDFs, the user should 
choose the PDT (Particle Distribution Tables) item of Menu 3. A more comprehensive set of 
PDFs is available in the LHAPDF j42[ library which the user can install separately and link to 
a CalcHEP model by using the Libraries model table. The source code for LHAPDF can be 
downloaded from the URL: 
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Menu 2 



Menu 1 



S.F.I OFF 
S.F.2 OFF 

Momentum Pl[GeV]=1000 
Momentum P2[GeV]=1000 

First particle unpolarized 
Second particle unpolarized 



■>■ Menu 3 



OFF 

ISR&Beamstralung 
Laser photon beam 
Equiv.Photon. Appr. 
PDT 
LHA 



Menu 4 



parton dist. alpha OFF 
alpha(MZ)= 0.1184 
nf= 5 

Order = NLO 
mb(mb) = 4.20 
Mtop(pole) =172.5 
Qfact = 91.197 
Qren = Qfact 
Alpha(Q) plot 



Subprocess 
IN state 




Menu 10 



All Constraints 
Masses, Widths, Branchings 



Menu 11 



All Particles 
G Zero 



Phase space mapping 



Monte-Carlo simulation 
ID integration 



Menu 6 



nSess = 5 
nCalls = 10000 



Set Distributions 
Start integration 
Display distributions 
Clear statistics 
Freeze grid OFF 
Clear grid 
Event Cubes 10000 
Generate Events 




Menu 5 



Breit-Wigner range 2.7 
T-channel widths OFF/ON 
Gl in t-channel OFF/ON 
Gl in s-channel OFF/ON 



Menu 9 



Kinematics 
Poles 



Menu 8 



Set precision 
Angular dependence 
Parameter dependence 



Menu 7 



Number of events=10000 
Launch generator 



Regenerate events ON 



Figure 2: A mcnu-trcc for the numerical session of CalcHEP 



http : //projects .hepforge . org/lhapdf / 

which also contains instructions for the installation of LHAPDF. To use the LHAPDF parton distri- 
bution functions in CalcHEP, the user should add the line 

-L<path_to_lhapdf> -ILHAPDF 

to the Libraries model table. This is sufficient to generate and compile the code for a process which 
creates the executable $WORK/results/n_calchep. However, it may not be sufficient to launch it. 
If libLHAPDF.so is located in a system area such as /usr/lib, then the library will be detected 
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automatically. Otherwise, information about the location of the shared library needs to be provided 
with environment variables. We recommend to add the instructions 

export LD_RUN_PATH=<path_to_lhapdf > 

to the calchep script in the $WORK directory and 

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH : <path_to_lhapdf > 

to the calchep_batch script in the same directory where <path_to_lhapdf > is the path to the 
LHAPDF library. By setting LD_RUN_PATH in the calchep script, the user does not need to set this 
environment variable again before starting the generated n_calchep later. Also, using LD_RUN_PATH 
in the calchep script allows the LHAPDF library to be updated without the user recompiling 
n_calchep. If the linking of LHAPDF is successful then the LHA item will appear in Menu 3. 

4-2. SLHA formatted files 

The Constraints menu allows the user to generate a complete SLHA file with all the particle's 
properties for a model including the particles' masses, widths and branching ratios. Since this file is is 
generate in SLHA format, the resulting file can be used by external programs such as MC generators. 

To create this SLHA file, the user should choose the Constraints option of Menu 1, go to the 
Mass, Widths, Branching submenu [Menu 10] and then choose the All Particles option [Menu 
11]. When this option is chosen, CalcHEP calculates the widths and branching ratios for the particles 
and writes all the information in the SLHA file. When it is finished, CalcHEP displays the meassage 

See results in file 'decaySLHA_n.txt' 

on the screen, where n is an integer. We note that these SLHA files can also be created during the 
symbolic session through the All Constraints menu item (Menu 4 of Fig. [1]). 

It is well known that for a correct calculation of the Higgs width and branching fractions, the 
QCD loop corrections must be included. This can be done by using running quark masses and 
yukawa couplings. In the default CalcHEP models, we include the following running quark masses 
which are coded in the SLHAplus package 

McRun(Q) MbRun(Q) MtRun(Q) 

and the effective quark masses 

McEff(Q) MbEff(Q) MtEff(Q) 
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which depend on the QCD scale (Q) and should be used to calculate the Yukawa couplings (in 
the Constraints table). The effective masses calculated at the Higgs mass scale provide the correct 
partial Higgs width at NNLO. Parameters with the scale Q as an argument have a special meaning 
in CalcHEP. When CalcHEP calculates the particle width it substitutes the particle mass for the 



scale Q. Further details can be found in 33 



To keep gauge invariance in tree level calculations, the particle's pole mass must be the same as is 
used for the Yukawa coupling. For the c and b quarks, the effect is small at high energies. However, 
for the t quark the usage of the effective mass can lead to the wrong decay modes for BSM particles. 

4-3. Built-in kinematical functions 

CalcHEP has a wide set of built-in kinematical phase space functions which can be used to 
implement various kinematical cuts and/or to construct distributions [§. These functions are defined 
via the names of the outgoing particles and are called with the syntax 

Naine[-,_] (P1[,P2,P3. . .]), 

where Name is one capital letter specifying the function, the ~ and _ are optional function modifiers 
useful in the case of identical outgoing particles (described below), and P1[,P2,P3. . .] are the 
outgoing particles involved in the observable. The available functions are: 

A : A (PI [,P2, . . .] ) gives the angle between PI and the combined momentum pp2 + pps + ■ ■ ■. If 
only one particle is specified, as in A (PI), the angle between PI and the first incoming particle 
is returned. The angle is given in degrees. 

C : C(P1 [,P2, . . .] ) gives the cosine of the angle defined above for A (PI [,P2, . . .] ). 

J : J(P1,P2) gives the jet cone angle between PI and P2. The jet cone angle is defined as 
■v/Ay^ + A<y9^, where Ay is the difference in pseudo-rapidity and Aip is the difference in az- 
imuthal angle between PI and P2. 

E : E(P1 [,P2, . . .] ) gives the energy of the combined momentum ppi + pp2 + ■ ■ ■. 

M : M (PI [ , P2 , . . . ] ) gives the invariant mass of the combined momentum ppi + pp2 + ■ ■ ■■ 

P : P(P1,P2[,P3, . . .] ) first boosts into the cms frame of P1,P2[,P3, . . .] and then takes the 
cosine of the angle between PI (in the cms frame) and the boost direction. 

T : T(P1 [,P2, . . .] ) gives the transverse momentum of the combined momentum ppi +pp2 + ■ ■ ■. 



^We note that the user can also write his/her own routines for kinematical functions. Further details can be found 
in Section H3I 



14 



Y : Y(P1 [,P2, . . .] ) gives the rapidity of the combined momentum ppi + pp2 + 



N : N(P1 [,P2, . . .] ) gives the pseudo-rapidity of the combined momentum ppi + pp2 + ■ • •• 
W : W(P1 [,P2, . . .] ) gives the transverse mass of the particle set S = {P1,P2, . . .} given by 



where rrii and pj are the mass and transverse momentum respectively of the ith particle. 

For example, M(ni,M) returns the invariant mass of a /i^ pair. 

In situations where there is more than one identical outgoing particle, all permutations of that 
particle are tested for cuts while their histograms are added. For example, suppose we have the 
process p, p — )■ j, j, j where j is a jet. The cut J ( j , j ) would be applied to all six possible combinations 
of the three jets. On the other hand, if this observable were used for a distribution, each of the six 
combinations would be binned for the histogram. In other words, the histograms for each combination 
are added together. On the other hand, each particle is only used once for each observable. So, for 
example, J(j,j) is never the jet cone angle of a jet and itself. The optional modifiers " and 
select the maximum and minimum value for the kinematical function among all permutations. For 
example, J_(j , j) calculates the jet cone angle of all pairs of jets and returns the smallest one for 
the cut or histogram. 

Although the momenta of incoming particles can not be measured directly, distributions of these 
momenta can still be interesting and useful to understand the details of the collision. For this. El 
and E2can be used for the energy of the first and second incoming particle, respectively. The total 
partonic CMS energy can be obtained with M12. 



Aliases can be defined (see Menu 1 in Figure |2]) for particle sets which will be substituted in the 
kinematical functions presented above. The user should enter each alias on a separate line where the 
name of the alias belongs in the first column and the particles that are contained in the alias belong 
in the second column. For example, a jet could be defined as: 

Name I Comma separated list of particles 
j |u,U,d,D,c,C,s,S,b,B,G 

in the default SM. A positively charged lepton of first or second generation might be defined as: 

Name I Comma separated list of particles 




4.4- Aliases 



1+ 



|E,M 
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in the default SM. The user can make any ahas definitions he/she hkes as long as the names do not 
match any particle names. These aliases can be used in the cuts and distribution definitions. For 
example, a pt cut can be placed on QCD quarks and guons with one line using an alias (T(j) rather 
than specifying a separate cut for each quark and guon. Note that all particles included in an alias 
are treated in the same manner as identical particles. So, all combinations are tested for cuts and 
binned for histograms. 

4-5. User defined kinematical functions 

To implement a new observable for cuts and distribution one can write a usrf un routine which 
should be a C-code function. The code of this function can be linked to the numerical session by 
adding it to the CalcHEP model Libraries table. The user can then call these observables as Ucode 
where code is a user-defined string which is passed to the usrfun routines for processing. These 
user-defined observables can be used in cuts and distributions. The full prototype of the usrfun 
function is 

double usrfun(char *code, int nin, int nOut, double *pvect, char **pName, int *pdg) ; 
where 

- nIn is the number of incoming particles. 

- nOut is the number of outgoing particles. 

- pvect is an array containing the momenta of the incoming and outgoing particles. The mo- 
mentum of the z*'' particle (qi) where i goes from to nIn + nOut — 1 is given by 

qi [k] =pvect [4*i+k] 

where k goes from to 3. qi [0] =pvect [4*i] gives the energy (which is always positive), 
qi [3] =pvect [4*i+3] gives the component of the momentum along the axis of collision and 
qi [1] and qi [2] give the transverse components of the momentum. 

- pName is an array of strings which contain the names of the particles. pName [0] gives the 
name of the first incoming particle, pName[l] gives the name of the second incoming particle, 
pName [2] gives the name of the first outgoing particle, and so on. 

- pdg is an array of PDG ID codes for the particles. 
Some further functions which the user may find helpful are: 

int findvaKchar *naine, double *value) ; 

int qnumbers(char *pname, int *spin2, int *charge3, int *cdini) ; 
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The first accepts a parameter name (independent or dependent) and fills the value of the parameter. 
The second accepts a particle name and fills the quantum numbers of the particle. Further details 
of these functions can be found in Section [TOl 

We provide an example usrfun routine in the file $CALCHEP/utile/usrfun. c which calculates 
the transverse mass of two particles. 

4-6. Cuts and distributions 

The Cut item of Menu 1 allows the user to apply cuts to the current process. This is done by 
filling in the cuts table with the kinematical function (second column), the minimum limit for the cut 
(third column) and the maximum limit for the cut (fourth column). The minimum and maximum 
limits for the cut should be algebraic functions of the model parameters and numbers. One of the 
limits can be left blank, in which case that limit is not applied. If there is an exclamation mark ( ! ) 
in the first column, the cut is inverted. For example 

! I Parameter I Min bound I Max bound 
I M(b,B) I Mh/2 I Mh*2 

means that the invariant mass of a b-quark and an anti-b-quark must be between half the Higgs 
mass and twice the Higgs mass. 

The syntax for the distribution table [Menu 6] is similar to that of the cut table. Both one- 
and two-dimensional distributions are supported. The distributions are filled during Monte Carlo 
integration and can be viewed graphically with the Display distribution item of Menu 6. An 
example of a distribution in the GUI is presented in Fig. [3l These distributions can be saved in a few 
different formats. The first is to the file plot_n.txt where n enumerates the plot files. This file has 
the data in two space separated columns. It also contains example instructions at the top for using 
this file with PAW and Gnuplot. The data in these files can be re-displayed later by CalcHEP by 
the plot_view routine as in 

$CALCHEP/bin/plot_view plot.N . txt 

The Clear Statics function of Menu 6 resets all the data. 

We note that the kinematic functions used in the Cut and Distribution tables can contain 
particles which are not present in the current subprocess. When this occurs, these cuts are ignored 
and these distributions are not filled. In this way, cuts and distributions can be defined once for all 
subprocesses. When a different subprocess is chosen [Menu 1], the cuts and distributions that apply 
are automatically turned on. 
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Figure 3: Plot of the invariant mass of a muon and an anti-niuon for the process e,E— >-m,M with an initial energy of 
200 GeV and ISR energy smearing turned on. 



^.7. Monte-Carlo simulation and event generation 



CalcHEP uses VEGAS [43|, |4J] for Monte Carlo integration. The Start Integration function 
of Menu 6 launches a cycle of NSess VEGAS sessions with nCalls integrand calls for each session. 
If the switch Freeze grid = OFF, VEGAS improves the integration grid after each sessioijfl. Table 
I4.7( left) presents an example of a Vegas session with the grid being improved as evidenced by the 
steep decline in the Monte Carlo uncertainty in the Error column. Although the grid is improved 
by the end of the session, the final uncertainty (in the final line) is still large because it includes the 
results of all ten sessions, including the initial sessions when the grid was not yet improved. It is a 
good idea to clear the results once the grid is improved and rerun VEGAS. This is done by using the 
Clear statistics menu item and then Start Integration again. An example of a VEGAS session 
after the grid has been improved and the statistics cleared is shown in Table HTTT right) . The Monte 
Carlo uncertainty is small for all ten sessions and the resulting cross section has a correspondingly 
small uncertainty. 

When Freeze grid = ON [Menu 6], VEGAS will prepare the event generator during the VEGAS 



^The importance sampling algorithms is used here. 
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IT 


Cross section [pb] 


Error [%] 


nCalls 




IT 


Cross section [pb] 


Error [%] 


nCalls 


Eff. 




1 


1.8319E+00 


1.29E+01 


9826 




1 


2.0516E+00 


2.33E-01 


9826 






2 


2.0575E+00 


5.76E+00 


9826 




2 


2.0587E+00 


2.27E-01 


9826 


8.5E-01 




3 


1.9409E+00 


4.88E+00 


9826 




3 


2.0506E+00 


2.27E-01 


9826 


7.5E-01 




4 


2.2081E+00 


6.63E+00 


9826 




4 


2.0450E+00 


2.28E-01 


9826 


7.1E-01 




5 


2.0717E+00 


2.44E+00 


9826 




5 


2.0511E+00 


2.27E-01 


9826 


6.9E-01 




6 


2.0588E+00 


7.72E-01 


9826 




6 


2.0549E+00 


2.26E-01 


9826 


6.7E-01 




7 


2.0624E+00 


3.93E-01 


9826 




7 


2.0623E+00 


2.29E-01 


9826 


6.6E-01 




8 


2.0501E+00 


2.81E-01 


9826 




8 


2.0610E+00 


2.28E-01 


9826 


6.5E-01 




9 


2.0472E+00 


2.48E-01 


9826 




9 


2.0516E+00 


2.31E-01 


9826 


6.5E-01 




10 


2.0547E+00 


2.24E-01 


9826 




10 


2.0564E+00 


2.27E-01 


9826 


6.4E-01 




<> 


2.0383E+00 


1.58E+00 


98260 


0.9 


<> 


2.0543E+00 


7.23E-02 


98260 


6.4E-01 


1 



Tabic 1: Result of a cycle of 10 Vegas sessions for the process e,E^-m,M with an total energy of 400 GcV beams 
and ISR smearing turned on. The left side corresponds with an intial cycle where the grid is improved and Freeze 
grid=OFF. The right side corresponds with a second cycle after the grid has been improved and the statistics have 
been cleared. Freeze grid=ON has also been set in the second cycle. As a result, the generator grid is also being 
improved. 

sessions. With each VEGAS pass, the event generator will improve its estimates of the maximum 
differential cross section (or differential partial width) in each event generation cube. The number 
of event generation cubes can be set with the Event Cubes item of [Menu 6] as in 

Freeze grid = ON 
Event Cubes 10000 

The larger the number of event cubes, the longer it takes to improve the event generator but the 
more efficient the generator. In each cube, the maximum value will be set at 1.2 times the largest 
differential cross section (or differential partial width) that VEGAS finds. Since with each pass the 
estimates for the maximums will become larger (as VEGAS finds higher values), the event generator 
efficiency will become smaller. The event generator is prepared when the efficiency stabilizes. An 
example of event generator preparation is shown in Table ITW right) . where the Eff column gives the 
estimated efficiency of the event generator after each VEGAS session. 

The event generator preparation in the above paragraph is based on the Von Neumann algorithm 
(see jssj, p. 202) where a phase space point x is sampled with a probability F{x) (where in our 
case F{x) is the maximum deteremined during the event generator preparation) and accepted with 
probability f{x)/F{x) (where for us f{x) is the differential cross section or partial width at x). 
However, because the maximums are determined by the calculation of random phase space points 
(by the VEGAS Monte Carlo), there are times when f{x) > F{x) will occur during event generation. 
If CalcHEP finds such a point x, it will increase F[x) for the the rest of the event generation. 
Furthermore, if Regenerate events [Menu 7] is set to OFF, CalcHEP will accept this event and give 
it the weight f{x)/F[x) > 1. On the other hand, if Regenerate events is set to ON, CalcHEP will 



19 



regenerate all the events from that event cube. When CalcHEP is finished generating the requested 
events, it will display information about the events on the screen as in 



Event generated: 10000 
efficiency: 6.4E-01 
Max Event multiplicity: 2 
Multiple events (total) : 3 

including whether events with weight greater than 1 were generated and request whether the user 
would like to accept the generated events. 

5. Working with files from numerical session 

5.1. File naming convention 

CalcHEP keeps an internal counter of numerical sessions. Any time a parameter is changed 
that affects the numerical results, CalcHEP increments the session number. All the parameters as 
well as the state of the random number generator and the integration results are stored in the file 
$WORK/results/session.dat. This allows the numerical session to be run later starting from the 
same state. The session number is displayed on the screen in the GUI. Furthermore, the session 
number is used in the names of some files written by CalcHEP in order to connect them with a 
particular session. These files are 

• prt_N which contains complete information about the session parameters (including model 
parameters, momenta, structure functions, cuts, etc.) as well as some of the results from the 
VEGAS session; 

• decaySLHA_N which contains information about the particle spectrum of the model and includes 



the particles' decay channels in the format of j40 



• distr_N which contains the full distribution data filled by VEGAS which can be viewed later 
as described in Section 15. 2( 

• events_N.txt which contains the generated events; 
where N is the session number. 
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5.2. Distribution files 

The distributions generated by CalcHEP can be displayed after a numerical session has finished 
with the command 

$CALCHEP/bin/show_distr distr.N 

where N is the session number where the distribution was generated. The distributions generated in 
different numerical sessions can be combined by the command 

$CALCHEP/bin/sum_distr distr.A distr.B . . . > distr.sum 

where distr_A, distr_B . . . are the distribution files from different sessions and distr_sum is the 
file where the results should be written. This program only combines distributions with exactly the 
same kinematical variable and exactly the same distribution limits. For example, M(b,B) and M(B,b) 
are treated as different distributions are never summed. However, the distribution M( jet, jet) where 
the alias name jet has been defined appropriately (see Section are combined if their distribution 
limits are identical as well. 

5.3. Events 

CalcHEP writes events in the format presented in [l|. However, the the LHE format 45 1 has 
become widely used now. For this reason, we include a script to rewrite event files in LHE format 
which can be run as in: 

$CACLHEP/bin/event21he events_N.txt > events.N.lhe 

where N is the session number for the generated events. Additionally, CalcHEP has routines to read 
the event files and histogram the events. The notation for the kinematical observables is the same 
as in Section 14.31 These routines can be run as in the following examples: 

$CALCHEP/bin/events2tab Variable Min Max Nbin < events.txt > tab.txt 
$CALCHEP/bin/lhe2tab Variable Min Max Nbin < events. Ihe > tab.txt 

where Variable is the kinematic observable and must be in quotation marks (e.g. "M(m,M)"), Min 
and Max are the histogram's minimum and maximum values respectively, Nbin is the number of 
bins, events.txt and events. Ihe are the event files in original and LHE format respectively and 
tab.txt is the file where the results should be written. In the case of the lhe2tab, the PDG ID's 
of the particles should be used in place of the particle's names since the particle names are absent 
in the LHE format. The resulting histograms can be displayed on the screen and transformed into 
PAW, Gnuplot, Mathematica and LTgX formats by the plot_view routine. For further analysis 
CalcHEP contains a program that creates PAW NTUPLES from LHE files which is used in the 
following way 

$CALCHEP/bin/nt_maker events. Ihe 

where events. Ihe is an event file in LHE format. 
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5.4- Event Mixing and LHE format 

Typical collider processes contains many subprocesses that differ only by the initial state and/or 
final state particles. For example, at the LHC, the initial states are two colliding protons which, 
however, are composed of quarks, antiquarks and gluons. It is desirable to combine different channels 
in one event file and connect production events with decays so that the final events are fully or partial 
decayed. The CalcHEP routine which does this job is event_mixer and can be used as in 

$CALCHEP/bin/event_mixer Lumi Nevent dirl dir2 

where Lumi is the maximum integrated luminosity (in units of Nevents is the number of 

events to generate, and dirl dir2 . . . are the directories where the production and decay events 
are stored. If Nevents is smaller than Lumi times the final cross section (we will call this N^ax), 
then Nevents will be produced. If, on the other hand, Nevents is larger, then event .mixer will stop 
when it reaches N^ax- If event_mixer comes to the end of a decay file before it is finished producing 
the requested number of events, it prints a message to stderr and returns to the beginnin g of the 



decay event file. The resulting events are stored in th file event_mixer . Ihe in LHE format [45 . 

Before event_mixer begins combining events, it reads the file decaySLHA.txt which should be 
stored in the current directory. This file should contain the quantum numbers, masses, widths and 



branching ratios of the particles of the model written in SLHA format [40|]. This file is used to 
define the correct widths and branching ratios of the decaying particles. If this file is not present, 
event_mixer will determine the branching ratios from the decay event files that it uses. However, 
please note that if decaySLHA.txt is not present and all the decay channels for an unstable particle 
are not present, event_mixer will likely produce incorrect results. The decaySLHA.txt file can be 
produced by the CalcHEP numerical session (see Section [4.21) . We strongly recommend to always 
include it when using event .mixer. 

After reading decaySLHA.txt but before combining events, event_mixer prints to stdout the 
final cross section and the maximum number of events that can be generated. For example, 

2.368E-01 -total cross section [pb] 
10098 -maximum number of events 

To get this information before mixing the events, simply request events. 
Some special features of LHE file generated by CalcHEP are: 

• The decays are applied recursively. 

• A decay history of each event is stored in the LHE file. This includes information about the 
parent particles and their mean life time. This information can be used for proper hadronisation 
and detector simulation. 
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• When connecting decays, event_mixer uses a Breit-Wigner virtual mass distribution, where 
we assume that the matrix elements of the subprocesses do not depend strongly on the off-shell 
momentum. 

• If decaySLHA.txt file was detected it is attaches to the output inside <slha> . . . </slha> 

tags according to the LHE convention. This allows parton shower generators like Pythia and 
Herwig to implements the decays of BSM particles. 

• In case of an incomplete set of decay channel event files (which is detected via a differ- 
ence between the sum of the partial widths from the decay event files and that stored in 
decaySLHA . txt) the resulting cross section is reduced correspondingly. 

• In spite of Breit-Wigner mass smearing for decays our procedure does not break momentum 
conservation. The output file contains a line which records the largest deviation from energy 
momentum conservation. An example is 

#lost_momenta_max/Etot 7.9E-11 1.3E-12 1.3E-12 8.0E-11 

Typical value should be on the order of 10^^° since the original event files contain 11 digits Of 
precision for the particle momenta. 

The generated event_mixer . Ihe file also contains an XML header spanned by the tags <hepml> 
. .</hepml> written in HepML |46j] format. This allows to automatically upload the LHE file to the 
CERN Monte-Carlo Database (MCDB) using the commancill 

. /upload2incdb_hepinl .pi -header hepml event_inixer . Ihe 

If the file run_details.txt is found in the current directory, event_inixer will include the informa- 
tion in this file in the header. The format for this file is a keyword value pair on each line and is the 
same as the format for a batch file used with the batch interface. Further details can be found in 
Section O 

6. CalcHEP blind mode and batch scripts 

Initially CalcHEP was designed for interactive calculations with a graphical user interface. How- 
ever, there are times when a batch system is ideal. For example, when a calculation takes a very 
long time, or the user is interested in doing scans over parameter space or over subprocesses. 



^The upload2mcdbJiepml.pl script can be downloaded from the MCDB website https : \\mcdb . cern. ch. 
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In order to solve this problem, the blind mode was introduced 47|, ll9|. If the -blind flag is used 
with either s_calchep or n_calchep, they will read the next argument and interpret it as a series 
of commands. These commands are written in a special notation which matches the keystrokes the 
user would perform during an interactive session. For example, the commancifl 

$CALCHEP/bin/s_calchep -blind "f Standard Model-[{-[e ,E->in,M{{ [{ [{{0" 

would generate the C code for the process e,E->in,M in the Standard Model. Some of the characters 
in the command string have a special meaning. Here are a few of them: 



] 


-Up 


} 


-Escape 


[ 


-Down 


f 


-find or search for the string in a menu 


{ 


-Enter 


0-9 


-Function keys or numeric input according to context 



Determining an appropriate command sequence string can be difficult for a user. For this reason, 
both s_calchep and n_calchep can be run with the flag +blind. In +blind mode, the interactive 
graphical interface opens and the user can run them as usual. When the user quits, CalcHEP writes 
the command sequence string to stdout. The user can then copy it and modify as appropriate to use 



in -blind mode. Further technical details can be found in |47l . Il9 . 

The -blind mode was used to write several scripts which are stored in the $CALCHEP/bin direc- 
tory. First of all, there are several scripts which change the parameters of a numerical session: 

• set.momenta pi p2: This script updates the momenta of the incoming particles to pi and p2 and 
then quits. 

• set_parani namel valuel name2 value2 . . .: This script changes the numerical values of one or 
more of the independent model parameters namel, name2, etc. to valuel, value2, etc. respectively 
and then quits. 

• set_param File: In this case, this script changes the numerical values of the independent model 
parameters as specifled in the flle File. File must have each model parameter on a separate line 
with the name coming flrst followed by the new numerical value, separated by white space. 

• set_vegas nSessl nCallsl nSess2 nCalls2 EventCubes : This script sets the parameters of a 
two loop Vegas calculation used by the run_vegas script presented below. The meaning of the pa- 
rameters was explained in Section 14. 7[ They can be seen in Figj2j The statistics are cleared and the 
grid is frozen between session 1 (deflned by nSessI and nCallsl) and session 2 (deflned by nSess2 
and nCalls2). 

The full set of parameters for the numerical session are stored in the flle session.dat. When the 
interactive GUI session (n_calchep) runs or when any of these scripts run, they update session.dat 
with the new parameters before quitting. As a result, when the interactive GUI session (n_calchep) 



^One has to remove tmp/safe file before launcliing this command. 
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or these scripts are run later, they begin with the updated parameters of the last session. This allows 
the user to prepare for a blind calculation in two ways. The user can either run the interactive GUI 
session (n_calchep) and set all the parameters as needed or he/she can run these scripts to set the 
parameters as required. Once the parameters are set appropriately, the folowing scripts allow to run 
VEGAS: 

• run_vegas: This script runs VEGAS according to the parameters in session.dat. 

There are several scripts which perform scans which are based on run_vegas. The output for 
these cycles is stored in text files whose names have the form xxx_jl_j2, where jl is the session 
number when the script began and j2 is the session number when it finished. If there are distribu- 
tions specified in session.dat, they are stored in the files distr_k where jl< k< j2. These scripts 
are: 

•pcin_cycle pcmO step N: This script scans the cross-section over the center of mass energy. For 
each point in the scan, it updates the momenta of the initial state particles and then runs the Vegas 
Monte Carlo integration. It begins its calculations with the momenta of the initial state particles 
equal to pcmO and increases in steps of size step for a total of N steps. When it is finished, it writes 
the resulting cross-sections to the file pcm_tab_j l_j2. 

•naine_cycle name valO step N: This script scans the cross-section over a model parameter's value. 
For each point in the scan, it updates the parameter name and then calculates the cross-section. When 
it is finished, it writes the resulting cross-sections to the file name_tab_j l_j2. where name is the 
name of the parameter. 

• subproc_cycle L Nmax: This script calculates the cross-section and generates events for each sub- 
process. When it is finished, it adds the cross-sections together and prints the total cross-section to 
the screen. If there are distributions specified then they are added together and the resulting distri- 
bution is stored in the file distr_jl_j2. It also generates unweighted events for each subprocess. 
The number it generates is equal to the smaller of Nmax and the cross-section times the luminosity 
which is specified by L. It writes these events to the files events_k.txt where jl< k< j2. 
•par_scan < data.txt: This script calculates the cross-sections according to the grid for names 
and parameters given in data.txt file. The format of data.txt is 

name_l rLajne_2 . . . rLame_N 
val_ll val_12 . . . val_lN 



val_Ml val_M2 . . . val_MN 

where name_l name_2 . . . naine_N are the names of independent model parameters , while val_ll 
. . . val_lN are the values for the respective parameters to be used for the first calculation and 
val_Ml . . . val_MN are the values for these parameters for the last parameter point to be calculated. 
Note that this script does not sum over the subprocesses (i.e. it will do the calculation only for the 
subprocess currently chosen in session.dat). The results of the calculations are printed to stdout 
and can be redirected into a file with a command such as 

par_scan < data.txt > results.txt 
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where results.txt is the file where the resuhs should go. The output format repeats the input 
format but contains one additional column with the results of the calculation. 

•par_scan_sum < data.txt: This script calculates the cross-sections according to the parameter 
points in data.txt similarly to par_scan. However, this script calculates the cross section for all 
the available subprocesses and sums them together. 

•gen_events Nevents: This script can by launched after a successful VEGAS calculation including 
a session where the grid is frozen to improve the event generation grid. This can be done with the 
run_vegas script described in this section. The argument Nevents defines the number of events to 
generate. 

If any of these scripts ends with an error, a message is printed to stderr and the return value of 
the script can be seen by issuing echo $? on the shell. A description of the possible error codes can 
be found in the CalcHEP manual. 

7. Batch interface 

Although the shell scripts of the previous subsection greatly improve the users ability to run their 
desired processes in batch mode, there are still some limitations when doing large complex calculations 
involving scans over parameter space, many subprocesses and parallelization. To overcome these 
challenges, we have written a Perl script which we call the "batch interface". The main features of 
this Perl interface are: 

• The input is a pure text file we call the "batch file" . It consists of a series of keywords together 
with values for those keywords, with each keyword on a separate line. Most of the options 
available in the interactive session are supported by keywords in the batch file and thus most 
calculations can be done using the batch interface. 

• A library of subprocess numerical codes is utilized. Each time the batch interface is run, it first 
checks whether the subprocess numerical code exists. If it does, it reuses it and skips the often 
long process of code generation. Any requested numerical codes not in the library are then 
generated and added to the library. If the model changed, the numerical codes are regenerated 
as appropriate. 

• The numerical phase space integration is done and events are generated for each subprocess 
and the results are combined. Production and decay events are connected and the final event 
output is an LHE file with all the events fully decayed which can be used directly by Pythia 
or other software. 

• Multiple parameters can be scanned over. For each parameter point, the results are combined 
and stored with names unique to that parameter point for easy retrieval. 
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• Both the symbohc calculations and the numerical calculations are parallelized. Each subprocess 
and each parameter point are run as separate jobs and run on all available cpu cores. The 
number of cores available is set by the user as is the type of cluster software used. Multicore 
machines, PBS cluters and LSF clusters are currently supported. 

• The progress of the calculation is stored in a series of html files which can be viewed in a web 
browseiij. These html pages contain information about the progress of the calculation as well 
as the results of the calculations which are already finished. The final event files are linked as 
are the session.dat and prt files which give the full details of each individual calculation. Pure 
text versions of the progress pages are also created for situations where a web browser is not 
convenient. 

Once the user creates the batch file and runs the batch interface, no user input is required until it 
finishes. It can be run in the background and checked periodically. 

After the user has created their batch file, they would tj^ically run the batch interface from their 
CalcHEP work directory as 

. /calchep_batch batch_file 

where batch_f ile is the name of their batch file, which can be named anything the user likes. The 
batch interface will start by printing a message to the shell which will contain the location of the 
html progress reports which the user can simply copy and paste into their browser url window. The 
first time the user runs the batch interface, they can also run the following from the work directory 

. /calchep_batch -help 

which will complain that no batch file was present, create a series of html help files and quit. The 
location of the html help files will be printed to screen. This html help file can be opened in a web 
browser and contains all the details that are presented here. 

In the following subsection we describe each keyword available for the batch file and how to use 
it. An example batch file is stored in CALCHEP/utile/batch_f ile. 

7.1. Batch files 
Comments 

Any line beginning with a # is ignored by run_batch. The # has to be at the very beginning of 
the line. Some examples are: 



^The inspiration for creating html pages that showed the progress of the ealeulation was obtained from MadGraph 
3. 
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# This is ignored. 

#Model: Standard Model This is ignored. 

Model: # Standard Model (CKM=1) This is not ignored. 

Model 

The first section of the batch file should contain the specification of the model. This is done by 
model name and should match exactly the name in the CalcHEP model list. So, if you want to run 
the "Standard Model(CKM=l)" , you would specify this with the batch file line: 

Model : Standard Model (CKM=1) 

There is no default for this line. It must be included. 

The gauge of the calculation should also be specified in this section. Choices are Feynman and 
unitary gauge. CalcHEP is much better suited to calculation in Feynman gauge, but there may be 
times that unitary gauge is useful. This can be specified using the keyword Gauge as in: 

Gauge : unitary 

The default is Feynman. 

Process 

Processes are specified using the Process keyword and standard CalcHEP notation as in: 

Process : p,p->j,l,l 

Multiple processes can also be specified as in: 

Process : p,p->E,ne 
Process : p,p->M,nm 

As many processes as desired can be specified. When more than one process is specified, the processes 
are numbered by the order in which they are specified in the batch file. So, in this example, p , p->E , ne 
is process 1 and p,p->M,nni is process 2. This numbering can be useful when specifying QCD scale, 
cuts, kinematics, regularization and distributions allowing these to be specified separately for each 
process. There is no default for this keyword. It must be specified. 

Decays are specified using the Decay keyword and are also in standard CalcHEP notation as in: 

Decay : W->l,nu 

Again, multiple decays can be specified as in: 
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Decay : W->l,nu 
Decay : Z->1,1 

The default is to not have any decays. Cuts, kinematics, regularization and distributions do not 
apply to decays. 

It is sometimes convenient to specify groups of particles as in the particles that compose the 
proton or all the leptons. This can be done with the keyword Alias as in: 

Alias : p=u,d,U,D,G 
Alias : l=e,E,in,M 
Alias : nu=ne , Ne , run , Mm 
Alias : W=W+,W- 

As many aliases as necessary can be specified. These definitions can be used in cuts and distributions 
as well as in the processes and decays. The default is not to have any alias definitions. 

PDF 

The PDF of a proton or antiproton can be specified with the pdf 1 and pdf2 keywords which 
correspond to the pdfs of the first and second incoming particles respectively. Choices for these 
keywords are: 

• cteq61 (anti-proton) 

• cteq61 (proton) 

• inrst20021o (anti-proton) 

• inrst20021o (proton) 

• cteq6m (anti-proton) 

• cteq6m (proton) 

• cteq5m (anti-proton) 

• cteq5m (proton) 

• inrst2002nlo (anti-proton) 

• inrst2002nlo (proton) 

• None 
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An example for the LHC is: 

pdfl : cteq61 (proton) 
pdf2 : cteq61 (proton) 

The default is None. These keywords can also be used for electron positron colliders. For this process 
the available pdfs are: 

• ISR 

• ISR & Beamstrahlung 

• Equiv. Photon 

• Laser photons 

• None 

The following proton electron collider pdf is also available: 

• Proton Photon 

All of these pdfs must be typed exactly or copied into the batch file. 

If ISR & Beam is chosen, then the following beam parameters may be specified: 

Bunch x+y sizes (nm) : 550 
Bunch length (mm) : 0.45 
Number of particles : 2.1E+10 

The default values are the default values in CalcHEP and correspond roughly with the ILC. 
If Equiv. Photon is chosen for the pdf, then the following parameters may be specified: 

Photon particle : e~- 
iQlmax : 150 

Choices for the Photon particle keyphrase are mu~-, e~-, e"+, mu"+. The default is e"+. The 
default for the keyword I Q I max is the same as in the CalcHEP interactive session. 
If Proton Photon is chosen then the following may be specified: 

Incoming particle mass : 0.937 
Incoming particle charge : -1 
|Q~2|max : 2.1 

Pt cut of outgoing proton : 0.11 
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The defaults are the same as in the CalcHEP interactive session. 

The user can also use PDFs from the SLHA library if it is installed and the respective link is 
given in the model Libraries table. Here is an example of how to use PDF functions from the 
LHAPDF library: 

pdf 1 : "LHA : cteq611 . LHpdf : : 1 " 
pdf 2 : "LHA : cteq611 . LHpdf : : 1 " 

In this case, the value for pdf 1 and pdf 2 should be constructed using the following rules: 

1) It should be in quotation marks (" . . . "). 

2) It should begin with LHA. 

3) LHA should be followed by the name of a particular PDF set located in the PDFsets directory (e.g. 
cteq611 .LHpdf in the example above). 

4) The PDF set name should be follwoed by a particular PDF set number (e.g. in the example 
above corresponding with the central fit). 

5) This should be followed by either 1 (for a proton) or -1 (for an antiproton). 

6) The pieces from instructions (2)-(5) should be separated by a colon (:). 

Momenta 

The momenta of the incoming states can be specified with the keywords pi and p2 and are in 
GeV as in: 

pi : 7000 
p2 : 7000 

These are the default values for the momenta. 

Parameters 

The default parameters of the model are taken from the varsN.mdl file in the models directory. 
Other parameter values can be used if specified using the Parameter keyword. Here is an example: 

Parameter : EE=0.31 

This gives a convenient way of changing the default values of the parameters. Simply open CalcHEP in 
symbolic mode, choose to edit the model and change the values of the indepenedent parameters. 
These new values will then become the default values used by this batch program. There is no need 
to redo the process library. 
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Scans 

In some models it is useful to scan over a parameter such as the mass of one of the new particles. 
For example, if there is a new W gauge boson, it may be desireable to generate events and/or distri- 
butions for a range of masses for the W. This can be done with the Scan parameter. Scan begin. 
Scan step size and Scan n steps keyphrases. Here is an example: 

Scan parameter : MWP 
Scan begin : 400 
Scan step size : 50 
Scan n steps : 17 

This will generate the events and/or distributions for the model with the mass of the W set to 
400GeV, 450GeV, 500GeV,...1200GeV. As many scans as desired can be specified (including zero). 
For each scan, all four keyphrases have to be specified. Furthermore, if there is more than one scan, 
all four keyphrases have to be specified together. 

QCD 

The parameters of the QCD menu of the numerical session can be specified as in the following 
example: 

parton dist . alpha : ON 
alpha(MZ) : 0.118 
alpha nf : 5 
alpha order : NLO 
mb(mb) : 4 
Mtop(pole) : 174 
alpha Q : M45 

The default values are the ones in the interactive session. Not all the keywords have to be included 
in the batch file. It is sufficient to include the ones that need to be changed. 

The QCD scale can be specified in terms of the invariant mass of certain final state particles as 
in Mij which means that the QCD scale is taken to be the invariant mass of particles i and j. Or, it 
can be specified as a formula in terms of the parameters of the model as in Mt/2 which means half of 
the top quark mass. When specifying the scale in terms of the invariant mass of final state particles, 
the numbers are taken from the way the processes are entered with the Process keyword. So, if 
the process is specified as p,p->j,l,n, M45 means the invariant mass of the lepton and neutrino 
(l,n). The batch script will take care of renumbering if the subprocesses have the final state particles 
in a different order. It is also sometimes useful to use a different scale for different processes. For 
example, suppose the two processes p,p->j ,l,n and p,p->j , j ,l,n are specified in the batch file, 
the scales could be specified as in this example: 
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alpha Q :1: M45 
alpha Q :2: M56 

The number between the : : specifies which process to apply this scale and corresponds to the order 
in which the user specified the processes. If more than one process is specified, but the same non 
default scale is desired for all of them, this can be specified as in: 

alpha Q : Mt/2 

This specification will apply the same scale Mt/2 to all processes. 
Cuts 

Cuts are specified with the keywords Cut parameter. Cut invert. Cut min and Cut max and 
use standard CalcHEP notation, except for Cut invert which can be either True or False. These 
cuts are only applied to the production processes. They are not applied to the products of the decays. 
Here is an example: 

Cut parameter : T(le) 
Cut invert : False 
Cut min : 20 

Cut max : 

For each cut, all four keyphrases have to be present. As many cuts as desired can be included. 
Including Cut min or Cut max but leaving the value blank will leave the value blank in the CalcHEP 
table. If the cut should only be applied to a certain process, then the colon can be changed to : n : 
where n is the process number. 

Kinematics 

As the number of final state particles increases, it can be very helpful to specify the kinematics 
which helps CalcHEP in the numerical integration stage. This is done in exactly the same notation 
as in CalcHEP. The numbering corresponds to the order the particles are entered in the process in 
the batch file. Here is an example: 

Kinematics : 12 -> 34 , 56 
Kinematics : 34 -> 3 , 4 
Kinematics : 56 -> 5 , 6 

If multiple processes are specified, using a single colon will apply the kinematics to all processes. If 
different kinematics are desired for each process, then the :n: notation can be used. 
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Regularization 

When a narrow resonance is present in the signal, it is a good idea to specify the Regularization. 
This is done with the same notation as in CalcHEP. Here is an example: 

Regularization momentum : 34 
Regularization mass : MW 
Regularization width : wW 
Regularization power : 2 

Regularization for as many resonances can be specified as desired. Furthermore, different resonances 
can be specified for each process using the : n : notation. 

Distributions 

Distributions are only applied to the production process. The decays are ignored. Standard 
CalcHEP notation is used for the distribution parameter. Here is an example: 

Dist parameter : M(e,E) 

Dist min : 

Dist max : 200 

Dist n bins : 100 

Dist title : p,p->l,l 

Dist x-title : M(l,l) (GeV) 

The value for the keyphrase Dist n bins has to be one of 300, 150, 100, 75, 60, 50, 30, 25, 20, 15, 
12, 10, 6, 5, 4, 3 or 2. These are the values allowed by the CalcHEP histogram routines. The values 
given for the titles have to be pure text. No special characters are currently allowed. Gnuplot must 
be installed for plots to be produced on the fly and included in the html progress reports. More than 
one distribution can be specified. Also, distributions will work even if no events are requested. 

For this to work, the distributions have to be unambiguous and apply to all subprocesses the same 
way. For example, if a process is p,p->l,l,l and the distribution M(l,l) is given, then this routine 
will not know which two leptons to apply the distribution to and the results are unpredictable. If the 
process is p,p->l,l where l=e,E,m,M and the distribution M(e,E) is desired, this distribution will 
only apply to some of the subprocesses and give unpredictable results. Make sure your distribution 
is unambiguous and applies in exactly one way to each subprocess. If this is done, it should work. 
Nevertheless, check each distribution carefully to make sure it is being done correctly. 
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Events 

The number of events is specified with the keyphrase Number of events. This specifies the 
number of events to produce after all subprocesses are combined and decayed. If a scan over a 
parameter is specified, this keyphrase determines the number of events to produce for each value of 
the scan parameter. The number of events requested can be zero. In this case, the cross sections are 
determined and the distributions generated but no events are produced. Here is an example: 

Number of events : 1000 

The name of the file can be specified using the Filename keyword. If specified, all the files will 
begin with this name. Here is an example: 

Filename : pp-11 

If nt_maker has been installed in the bin directory, PAW ntuples can be made on the fly by 
setting NTuple to True as in: 

NTuple : True 

The default is False. 

The keyword Cleanup determines whether the intermediate files of the calculation are removed. 
This can be useful if many large intermediate files are created and space is an issue. On the other 
hand, it can be useful to keep the files when debugging is necessary. If this keyword is set to True, 
the intermediate files are removed. If set to False then they are not removed. Here is an example: 

Cleanup : False 

Parallelization 

The parallelization mode is set using the keyphrase Parallelization method and can be either 
local, pbs or Isf . In local mode, the jobs run on the local computer, in pbs mode, the jobs are 
run on a pbs cluster and in Isf mode, the jobs are run on an Isf cluster. If run from a pbs or Isf 
cluster, the terminal should be on the computer with the pbs or Isf queue. Here is an example of 
setting the batch to run in pbs mode: 

Parallelization mode : pbs 

Local mode is the default. 

If run in pbs mode, there are several options that may be necessary for the pbs cluster. All of 
them can be left blank in which case they will not be given to the pbs cluster. Here is an example 
of the options available: 
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Que : brody 
Walltime : 1.5 
Memory : 1 
email : name@address 

The que keyword specifies which pbs queue to submit the jobs to. Walltime specifies the maximum 
time (in hours) the job can run for. If this time is exceeded, the jobs are killed by the pbs cluster. 
Memory specifies the maximum amount of memory (in G) that the jobs can use. If this memory is 
exceeded by a job, the pbs cluster will kill the job. email specifies which email to send a message to 
if the job terminates prematurely. The default for all of these is whatever is the default on the pbs 
cluster. 

If run in Isf mode, there is one more option in addtion to the those above: 

Project : project_name 

Sleep time specifies the amount of time (in seconds) the batch script waits before checking which 
jobs are done and updating the html progress reports. If a very short test run is being done, then 
this should be low (say a few seconds). However, if the job is very large and will take several hours 
or days, this should be set very high (say minutes or tens of minutes or hours). This will reduce the 
amount of cpu time the batch program uses. Here is an example setting the sleep time to 1 minute: 

sleep time : 60 

The default is 3 seconds. 

When jobs are run on the local computer, the keyword Nice level specifies what nice level the 
jobs should be run at. If other users are using the same computer, this allows the job to be put 
into the background and run at lower priority so as not to disturb the other users. This should be 
between and 19 where 19 is the lowest priority and the nicest. Typically, it should be run at level 
19 unless the user is sure it will not disturb anyone. The nice level should be set both for a local 
computer and for a pbs or Isf batch run. The reason is that some jobs are run on the pbs or Isf queue 
computer even on the pbs or Isf cluster. Here is an example: 

Nice level : 19 

Level 19 is the default. 

Vegas 

The number of vegas calls can be controlled with the keywords nSess_l, nCalls_l, nSess_2 and 
nCalls_2. The values are the same as in CalcHEP. Here is an example: 
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nSess_l : 5 
nCalls.l : 100000 
nSess_2 : 5 
nCalls_2 : 100000 

The defaults are the same as in CalcHEP. 

Generator 

The following parameters of the event generation can be modified: 
sub-cubes : 1000 

The defaults are the CalcHEP defaults. 

Examples of batch files and the output results are given in section [TTJ 

7.2. Monitoring hatch session 

The batch session is started with the command: 

. /calchep_batch batch_file 

where batch_f ile is the name of the file that contains the batch instructions. The batch program 
will print the following to screen: 

calchep_batch version vv 
Processing batch: 

Progress information can be found in the html directory. 
Simply open the following link in your browser: 
file : ///WORK/html/index . html 

You can also view textual progress reports in WORK/html/index. txt 
and the other .txt files in the html directory. 
Events will be stored in the Events directory. 

where vv is the version number and WORK denotes the path to the calchep working directory. The 
user can view the progress in their favorite browser as well as check the results and details. Examples 
of the different batch files and the resulting output are given in Section [HI Among the details of 
the resutls, the html pages contain links to the prt_l and session.dat files for each subprocess 
and each scan parameter. These files contain the full details of the VEGAS session including all 
the parameters of the run. At the bottom of the prt_l file, there is a history of the results of the 
VEGAS phase space integration. The user may find these useful. 



37 



1.3. Results 

After the events and/or distributions are generated, they are stored in the Events directory. The 
prefix of the files is the name specified in the batch file plus either -single if no scans were specified 
or a string specifying the scan parameter values if one or more scans are specified. We will assume 
this is filename in the following. If events are requested, they will be stored in the files 

filename . Ihe 
f ilename .nt 

where filename . Ihe is the event file in Les Houches format and f ilename. nt is in PAW ntuple 
format. The ntuple file is only created if the keyword NTuple is set to True and nt_maker is present 
in the bin directory. If distributions are requested, they will be stored in the files 

filename . distr 
f ilename_l .png 
f ilename_2 .png 

where filename .distr is the raw distribution data and can be read by show_distr in the bin 
directory. The distributions generated on the fiy by the batch script are stored in the files ending in 
.png. 

8. Particle interaction model implementation 

A model of particle interaction in CalcHEP is stored in five tables, named Parameters, Constraints, 
Particles, Vertices and Libraries. These tables are stored in the respective files varsN.mdl, 
funcN.mdl, prtclsN.mdl, IgrngN.mdl, extlibN.mdl which are located in WORK/models/. The N in 
these file names refers to the model number. For all of these tables, a % at the beginning of any row 
means that that row is a comment and CalcHEP ignores it. We describe each of these tables in this 
section. 

8. 1 . Independent parameters 

The table Parameters contains all the independent parameters of the model. It consists of three 
columns, for example. 



Name 


Value 


Comment 


EE 


0.3123 


elecromagnetic constant 


SW 


0.481 


MS-BAR sine of the electroweak mixing angle 


MZ 


91.187 


Z-boson mass 


Mh 


125 


higgs mass 
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where 



Name: This is where the name of the parameter belongs. It can contain up to 11 characters. The 
first character must be a letter. The others may be either letters or digits. The underscore 
symbol is also permitted and CalcHEP is sensitive to the case of the characters. There is a set 
of reserved names which cannot be used for parameter names: 



— pl,p2,p3, . . . are reserved for particle momenta; 

— ml , . . . ,M1 , . . . are reserved for Lorentz indices; 

— G5 is used for the 7^ Dirac matrix; 

There is another subtelty that should be considered when naming parameters. Although 
CalcHEP is sensitive to the case of the parameters, Reduce is not. Therefore, if the user 
would like to use the CalcHEP results in Reduce, he/she should distinguish all names by more 
than case. Additionally, although CalcHEP allows underscores as part of parameter names, 
the underscore is treated differently by Mathematica. So, if the user would like to use the 
CalcHEP results in Mathematica, he/she should not use underscores in the parameter names. 

Value: This is where the numerical value for the parameter is stored. Dimensionful parameters should 
be in powers of GeV. 

Comment: This is where the user can enter a description of the parameter. It is ignored by CalcHEP and 
is purely for informational purposes. 

There are two parameters which are treated specially in CalcHEP. They are GG and Q. The first 
is reserved for the strong coupling 



CalcHEP forbids the appearence of this parameter in the Constraint table and in the Lorentz part of 
the Vertices table (see below). But, it can appear in the Factor column of the Vertices table. This 
parameter is evaluated by CalcHEP using QCD parameters which the user can view and/or modify 
in Menu 4 of Figj2l CalcHEP ignores the value of GG found in the Paramters table. The variable 
Q is intented to be used as a scale parameter in the quark effective masses and Yukawa couplings. 
When CalcHEP peforms a calculation of the particle width, it sets Q equal to the decaying particle's 
mass. This scale is then used to calculate the quark effectifve masses at that scale (see Sections 14.21 
and 19. ip . In all other cases, Q is set equal to its value from the Paramters table. 



i is reserved for the imaginary unit; 
Sqrt2 is reserved for a/2; 



GG 
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8.2. Dependent parameters 

The Constraints table contains all the dependent parameters of the model. It consists of two 
columns, for example, 



Name 


Expression 


CW 
MW 
GF 

%Local! 


sqrt(l-SW' 2) % cos of the Weinberg angle 
MZ*CW % W-boson mass 

EE'2/(2*SW*MW) '2/Sqrt2 % Fermi constant 



where 

Name: This is where the name of the parameter belongs. The restrictions on the names are the same 
as for the independent parameter names. 
Express: This is where the formula belongs which defines the value of this dependent parameter. The 
formula can contain the following: 

• integer and float point numbers, 

• independent parameter names contained in the Parameters table, 

• dependent parameter names defined above the current row, 

• parentheses () and arithmetic operators +, -, /, *, 

• the symbols i and Sqrt2, 

• standard functions from the C mathematics library such as sqrt(x) and sin(x). The 
full list of these functions is contained in the $CALCHEP/include/extern.h file, 

• functions from the SLHAplus package (see Section [OTT]) which collects many routines useful 
for model building, 

• the function if (x,y,z) which returns y if x> and z otherwise, 

• any user defined functions. The code containing these functions should be included in 
the Libraries table. Their prototypes should also be included in the Libraries table. 
If their prototypes are not included, CalcHEP assumes they return double type. A list 
of the resulting auto-prototyped functions appears in the WORK/results/autoprot .h file 
after compilation of the numerical code. 

Additionally, anything after the % symbol is considered a comment and ignored. This can be used 
to enter a comment about the dependent parameters. 

Some models contain thousands of dependent parameters. For a particular process, only a small 
subset of these is used. To reduce the size of the generated code, CalcHEP compiles only the 
dependent parameters involved in the current matrix element calculation. However, it is sometimes 
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necessary to have other dependent parameters compiled with the matrix element code in order to 
apply constraints such as on the particle spectrum. For this reason, CalcHEP splits all the dependent 
models parameters into two sets: the public parameters and the local parameters. By default, the 
public parameters are those that are required to calculate all the particle masses and widths as well 
as those that depend on external functions (except for dependence on standard C math functions) 
and all dependent parameters above any of these. All the dependent parameters below these are 
defined as local. The local parameters are not compiled unless they are needed for a matrix element 
calculation. If the user would like to force CalcHEP to include a larger subset of the dependent 
parameters in the numerical code, he/she can place the comment y„Local! in the Constraints 
table in the first column. CalcHEP will always include the parameters up to, at least, this point. 

The Constraints menu item of Fig. [2] displays only public parameters. These can be used along 
with global parameters in the specification of cuts and histogram limits, user-defined kinematical 
functions, and the QCD scale (see Section H]). The user-defined external functions can get the values 
of the independent model parameters and public dependent model parameters with the routine 

int f indval ( char *name, double *value) ; 

where name is the parameter name and *value is filled with the value of the parameter. More details 
can be found in Section 110.31 



8.3. Particles 

The particles are defined in the Particles table which consists of 11 columns. Each particle 
anti-particle pair is described by one row of the table. For example 



Full name 


A 


A 


PDG 


2*spin 


mass 


width 


color 


aux 


LaTex(A) 


LaTeX(A+) 


W-boson 


W+ 


W- 


24 


2 


MW 


wW 


1 


G 




W"- 


Higgs 


h 


h 


25 





Mh 


!wh 


1 




h 


h 



The columns are: 



Full name: The full name of the particle can be entered here. It is not used directly by CalcHEP. It is 
used to clarify what the short particle names mean. 

A&Ac: These columns are where the particle name and antiparticle name belong. More precisely, 
these columns contain the quantum field and its C-conjugate. The field operator acting on 
the vacuum is understood to create the corresponding anti-particle. Self-conjugate fields (such 
as photons and Majorana neutrinos) should contain the same name in both columns. Any 
printing character can be used in the particle name except white space, parentheses and the 
percent symbol (%). The length of the particle name can not exceed 8 symbols. For long 
particle names, we should note that the graphical representation of the diagrams might contain 
overlapping symbols. 
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PDG: This is where the PDG code 38| belongs. This number is used mainly for interfacing with other 



packages. For example, these codes are included in event files [45| in order to communicate the 
particle flavor to other programs. The parton distribution functions are also applied according 
to this number. The conventional PDG codes should be used for SM particles. For other 
particles, the user should ensure that the code is not reserved for another particles such as a 
meson or baryon. Otherwise, conflicts could arise when passing events to other programs, such 
as Pythia. 

2* Spin: This is where the spin of the particle is specified. It should be entered as the integer equal to 
twice the spin. In other words, should be entered for a scalar field, 1 for a spin 1/2 fermion, 2 
for a vector boson, 3 for a spin 3/2 fermion and 4 for a spin-2 boson. Spin 3/2 and 2 particles 
should be massive. 

Mass: This is where the mass of the particle is entered. If massless, can be entered. Otherwise, it 
must be a parameter name which is defined in either the Parameters table or the Constraints 
table. 

Width: This is where the width of the particle is entered. If the particle is stable, can be entered. 
Otherwise, it must be a parameter name. In this case, however, this parameter can be defined 
in the Parameters table, the Constraints table or it can be preceeded with the ! symbol. If 
it is preceeded with the ! symbol, CalcHEP will automatically calculate it when needed. In 
this case, the parameter should not appear in either the Parameters table or the Constraints 
table. When automatically calculating the width, CalcHEP first attempts the 1 — )■ 2 decays. 
If none are found, it attempts the 1 — ?■ 3 decays. If none are still found, it attempts the 1 — 4 
decays. If none are found at this point, it takes the width as zero. If information about particle 
widths was read from a SLHA file (See section [9?T1) . then the widths are not evaluated and 
CalcHEP substitutes the values it read from the SLHA file in the propagators. 

Color: This is where the color (SU(3)) representation is specified. Supported representations are the 
singlet (specified by a 1), the fundamental triplet (specified by a 3) and the octet (specified by 
a 8.) If the particle is specified as a triplet, the antiparticle is treated as an anti-triplet (the 3 
representation.) 

Aux: This field is primarily used to modify the propagator of the field. For most fields, this column 
will be left blank. The other possibilities are: 

— * : specifies that the propagator should be point like (all momentum dependence is 
dropped.) This can be used to construct 4-fermion propagators, for example. These fields 
can not appear as external states of processes. 
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— 1 and r : are used to specify that a fermion is purely left and right handed respec- 
tively. This can only be applied to massless fermions. The effect of this is that when 
CalcHEP averages over the spin of the incoming fermion, it takes into account that there 
is only one polarization for this particle. This is used, for example, for the SM neutrinos. 

— g : declares that the vector particle is treated as a gauge boson. In this case t'Hooft- 
Feynman gauge is used for the vector boson propagator and the ghost fields A . c and 
A.C (where A is the name of the vector boson) as well as the Goldstone boson A.f can 
contribute to the Lagrangian. A massless vertor particle must be treated as a gauge 
boson. In the absence of g in this column, the unitary gauge is always used for massive 
vector bosons and the ghosts and Goldstones associated with it are not used in Feynman 
diagrams. 

The Formulaes for the particle's propagators are presented in Section (18. 6p . 

The Aux column can also be used to specify a particle's electric charge. This charge is required 
by many external packages. CalcHEP already knows the charge of the SM particles and assigns 
it according to the particle's PDG code. It can determine the charges of many BSM particles 
by analyzing the Feynman rules and assuming they conserve electric charge. However, for some 
particles, this will not be sufficient to determine their charge. For this reason, CalcHEP allows 
to specify the charge of any BSM particle. Specifically, three times the charge should be entered 
in the Aux field. For example, a particle with electric charge of —1 would be enetered as -3, 
a particle with electric charge of 2/3 would be entered as 2 and so on. This charge must be 
written before other symbols in this column (if there are any.) We reiterate that this charge 
is not used to define the Feynman rules of the photon in calculations done by CalcHEP . The 
interactions of the photon are entered in the Vertices table along with all other Feynman rules 
(see Subsection 18.41 ) The electric charge defined in the Aux column of the Particles table is 
only used to communicate with other programs that require it. 

LaTeX: This is where the KTeX symbol for the particle and antiparticle are entered. These symbols 
are used when CalcHEP produces KT[t;X output for the Feynman diagrams that it constructs. 

8.4- Interaction vertices 

The Vertices table contains the Feynman rules for the model. For example. 



Al 


A2 


A3 


A4 


Factor 


Lorentz part 


h 


W+ 


W- 




EE*MW/SW 


m2.m3 



The first four columns (Al, A2, A3 and A4) specify the particles [antiparticles] involved in the 
interaction. These must be the particle names defined in the Particles table. The last of these 
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A4 may be empty, which specifies a three-point vertex. The first three columns must be nonempty. 
(The propagators are not specified in this table. They are hard coded. Section 18.61 contains further 
details.) 

The last two columns, Factor and LorentzPart define the vertex. If S is the action for a 
particular vertex, the vertex can be obtained by functionally differentiating with respect to the fields 
in the vertex as in 



where pi and refer to the 4-moment and Lorentz indices (if any.) The square brackets ([ and 
]) denote parts of the expression which only appear in some vertices, but not others. The Fourier 
transform is defined as 



The other pieces of Equation ([T]) will be discussed below. 

The Factor column is where the Factor from Equation ([T]) belongs. This must be a rational 
monomial constructed from the model parameters, integer numbers and the imaginary unit (i). It 
is best to factor as much as possible from the LorentzPart since the LorentzPart of the Feynman 
diagrams is usually the most time consuming and memory intensive part of the calculation. 

The LorentzPart column is where the LorentzPart from Equation ([1]) belongs. It must be a 
Lorentz tensor or a Dirac 7-matrix expression. The coefficients of the terms in this expression can 
be polynomials of the model parameters and scalar products of the momenta. The division operator 
(/) is forbidden from this column. It must be transferred to the Factor column or into a model 
parameter. 

The notation for Lorentz indices, momenta, contractions, and the metric tensor are similar to 
those in the Reduce package. The Lorentz indices of the fields in the vertex are labeled by a m for 
the first index and a M for the second index followed by the particle number for that vertex. For 
example, a vector field in the third column would have Lorentz index m3 while a tensor field in the 
second column would have Lorentz indices m2 and M2. The momenta use the symbol p followed by 
the same number. For example, a scalar field in column 1 would have momentum pi. A dot (.) is 
placed between two momenta, a momentum and its Lorentz index, and between two Lorentz indices 
(for the metric tensor.) Here are some examples: 



6S 



(1) 



6Allmj]{Pl) M2[„2](p2) SA3lms]{P3) ['^^4[„,](p4)] 



(27r)^5^(pi + P2 + Ps [+P4]) [C ^ ] Color Structure ■ Factor ■ LorentzPart , 




(2) 



pl.p2 means pi^ P2 
pl.M2 means pf^'^ 
ml.m2 means gmim2- 
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Dirac 7-matrices are written with a G and the momentum or Lorentz index in parentheses, while 
the 75 matrix has a 5 without parentheses. For example, we have: 

G(inl) means 7"^^ 
G(p2) means j'^P2fi 
G5 means 75 

The 75 matrix is defined by 

75 = i 7o7i7273 • 

The anti-commutation relation for the gamma matrices in CalcHEP notation is 

G(vl) G(v2) + G(v2) G(vl) = 2 vl.v2, 

where vl and v2 are either momenta or Lorentz indices. 

In the case of anti-commuting fields the functional derivative in Equation ([T]) is assumed to act 
from the right. The number of fermion fields in a vertex must be either two or zero. If the user 
would like to implement a four- fermion interaction, he/she must use an unphysical auxiliary field 
with a point-like propagator (see Subsections 18.31 and 18.61 for further details.) 

CalcHEP interprets the anti-particle spinor field as a C-conjugated particle field, rather than the 
Dirac conjugated field. These definitions are related to each other by 

which is the reason for the appearance of the C~^"^ matrix in Eq. ([T]). The particle and anti-particle 
fields can appear in the vertices in any order. Vertices can also contain two particle fields or two 
antiparticle fields. In other words, vertices that violate fermion number are allowed. 

Any fermion vertex can be written in two forms which depend on the order of the fermion fields. 
After permutation of the fermion fields, the LorentzPart is transformed according to 

G{vi) G{v2) . . . [G5] . . . G{vn) ^ {-G{vn)) . . . [G5] . . . {-G{v2)) {-G{v^)) , (4) 

where the order of the gamma matrices is reversed and each gamma matrix with a Lorentz index 
gets a sign change while the 75 matrix does not get a sign change. 

We note that the definition in Eq. ([T]), the LorentzPart has the appropriate symmetry property 
when identical particles appear in the vertex. This symmetry is not checked by CalcHEP, and its 
absence will lead to the wrong results. Equation |4] can be used to check this symmetry in the case 
of two identical Majorana fields in one vertex. It should also be noted that in the case of n identical 
particles, the functional derivative (P) gets a corresponding factor of n\ which should be included in 
the vertex. 
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The totally antisymmetric Levi-Civita tensor can be used in vertices. It is given by eps (vl , v2 , v3 , v4) , 
where vl, v2, v3, and v4 are either momenta or Lorentz indices. 

The Color Structure from Eq. ([1]) is not included in the Vertices table. CalcHEP substitutes it 
in automatically according to the following rules: If all the particles in the vertex are color singlets, 
CalcHEP inserts 1. If the vertex contains one fundamental and one antifundamental (3x3), the 
identity matrix is inserted. If the vertex contains two color octet fields (8x8), the identity matrix 
is inserted. If the vertex contains three color octet fields (8 x 8 x 8), it inserts 

— z/(al, a2, a3) 

where fa2a3 is the structure constant of SU(3) and the color adjoint indices al, a2, and a3 are taken 
in the same order they appear in the Vertices table. If the vertex contains a fundamental, an 
antifundamental, and a color adjoint field (3x3x8), CalcHEP inserts 

where X{i,j, a) are the Gell-Mann matrices. Other color structures are not implemented in CalcHEP, 
however, it is possible to construct them by means of an unphysical auxiliary field (see Subsections 
18. 3[ 18.61 and [7] for further details.) 

8. 5. External functions and libraries. 

The Libraries table is used to link external code and declare external functions. 

External libraries 

% LHAPDF shared library linking 

-L $(H0ME)/Packages/lhapdf-5.8.4/install/lib -ILHAPDF 
% LHAPDF static library linking 

y. $ (HOME) /Packages/lhapdf -5 . 8 . 4/install/lib/libLHAPDF . a -Igf ortran 
% function declaration 
extern double bsgnlo(void) ; 
% user library 

$ (HOME) /my.code/bsgnlo . a 

Lines beginning with a % are comments and are ignored by CalcHEP. Lines beginning with the 
keyword extern are considered to be prototypes of external functions defined in external code. These 
lines should include the full function prototype (including the semicolon at the end) on one line in 
the syntax of the C programming language. These functions can be used in the definitions of the 
dependent parameters in the Constraints table (see Subsection 18. 2[ ) 
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External code and libraries can be linked to the numerical code by using this table as well. The 
user should enter a list of the external code, libraries and any flags necessary for his/her model in 
this table. Some typical examples of external code are user defined kinematical variables which can 
be used in cuts and histograms (see Subsection 14. 3p and the LHAPDF hbraries (see Subsection 14.11 ) 
All lines which do not start with % or extern are concatenated and passed to the linker which 
creates the executable for numerical calculations. These lines can make use of environment variables. 
CalcHEP defines two in it's startup scripts (calchep and calchep_batch) that the user can make 
use of. They are $CALCHEP which is the path to the CalcHEP root directory and $WORK which is 
the path to the user's working directory. The user can also make use of his/her own environment 
variables. These environment variables can be used with or without parentheses (either $CALCHEP 
or $ (CALCHEP) is acceptable.) CalcHEP will translate between the two depending on whether they 
are used in a Makefile or in a shell environment. 

For functions presented in the SLHAplus package (Section 19. ip prototyping and special link 
instructions are not needed. 

8. 6. Propagators 

CalcHEP defines the propagators for particles of spin less than or equal to two. These propagators 
are hard coded and not modifiable by the user unless specified below. 
Spin : The spin-0 propagator is given by 

< 0|T[yl(pi),^+(P2)]|0 >= A,(pi,p2,M) - +^2) 



(27r)4(p2 _ M2) ■ 

Spin 1/2: The spin-1/2 propagator is given by 

< 0|T[A(pO, ^(P2)]|0 >= ( a + M) A,(pi,p2, M) , 

where j6 = p^7^. If the fermion is defined to be purely left or right handed (see Subsection 18. 3p . the 
propagator is defined as 

A(l±75) . , ... 

^ Ae(pi,P2,M) . 

Spin 1 : In unitary gauge, the propagator is given by 

mi m2 

< 0|T[A-nPi), (A™^)+(j>2)]0 >= -{g^'"^' + ^i^)A,(pi,p2,M), (5) 
while in t'Hooft-Feynman gauge, it is given by 
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We remind the user that a massless vector particle must be defined as a gauge boson (see Subsec- 
tion |831) 

Spin 3/2: The spin-3/2 propagator is given by 

<0|T[A-^(p),A-Hp')]|0>= (^-3(^ + M)(^7™-^1^) (6) 

Spin 2 : The spin-2 propagator is given by 

Auxiliary propagators : When massive particles are marked as auxiliary fields (see Subsection l8.3p 
by putting a * in the Aux column, the momentum dependence of the propagator is removed. 
Ac{pi,p2, M) is replaced with 

^{Pi + P2) 

and all terms proportional to the particle momentum p in the numerator are dropped. Auxiliary 
particles cannot appear as incoming or outgoing states. They are only used to implement point-like 
interactions. 

8. 7. Ghost and Goldstone propagators 

In addition to the fields enumerated in the Particles table, the Lagrangian can depend on a few 
other fields. In particular, gauge theories have Faddeev- Popov ghosts |49| and, if broken, Goldstone 
bosons. Furthermore, complex color structures require a special tensor auxiliary field. All of these 
fields are automatically generated by CalcHEP where appropriate by adding a final .c, .C, .f, .t 
or .T as described below. 

Faddeev-Popov ghosts and anti- ghosts, are generated for any gauge vector particle which is marked 
by a g in the 'Aux' column of the Particles table (see Subsection 18.31 ) The names of the Faddeev- 
Popov ghosts and anti-ghosts are constructed by adding a . c and . C, respectively, to the particle 
name. For example, if the gluon is named G, the gluonic ghost is named G . c and the gluonic anti- 
ghost is named G.C. The ghosts and anti-ghosts corresponding with the W+ and W- gauge bosons are 
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W+.c, W+.C, W-.c and W-.C. Hermitian conjugation transforms a Faddeev-Popov ghost into a ghost 
with the same sign whereas it changes the sign of the anti-ghost. For example, 



(G.c)+ = G.c 

[G.Cy = -G.C 

(W+.c)+ = W-.c 

(W+.C)+ = -W-.C 

Faddeev-Popov (anti)ghosts are anti-commuting, scalar fieldslll. The nonzero propagators for these 
fields are: 

< 0|r[A+.c(pi), A.G{p2)]\0 >=< 0|T[A+.C(pi), A.c{p2)]\0 >= A,{p,,p2,M), 

where A+ is the conjugate of A and M is the mass of the parent particle (we are assuming Feynman 
gauge.) 

The reason CalcHEP introduces the Faddeev-Popov ghosts at tree-level is that it sums over the 
unphysical polarizations of the gauge bosons in the external states as well as the physical polarizations 
in order to reduce precision loss due to large cancellations. The Faddeev-Popov ghosts (and the 
Goldstone bosons for a broken gauge theory) are required to cancel the unphysical polarizations. 



(See j49| for further details.) 



Goldstone bosons, are related to broken symmetries. In the case of broken gauge symmetries, they 
become the longitudinal degrees of freedom of the gauge boson. CalcHEP automatically generates 
these fields for massive vector bosons by appending a . f to the end of the gauge boson name. For 
example, the W+ and W- gauge bosons have the Goldstone bosons W+ . f and W- . f associated with 
them. These Goldstone bosons are commuting, scalar fields that satisfy the same conjugation rules 
as the gauge boson they belong with. For example, {W + .f)^ = W — .f. The nonzero propagators 
for these fields are: 

T[A+.f(pi), A.f{p2)] = A,(pi,p2,M), 

where A+ is the conjugate of A and M is the mass of the gauge boson (again we consider Feynman 
gauge.) 

Auxiliary tensor field.. Whereas the Faddeev-Popov ghosts and Goldstone bosons are standard 
elements of modern quantum field theory, this auxiliary tensor field was invented by the original 
CalcHEP authors in order to construct complicated color vertices such as the four-gluon vertex. 
These auxiliary fields are automatically generated whenever a particle is defined with a nontrivial 



''The "well-known spin-statistics relation is not valid for unphysical fields. 
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SU{3) color representation by adding .t and .T to the particle name. Two auxiliary tensor fields 
are generated automatically and are typically used for a constraint and a Lagrange multiplier. 

These auxiliary fields are commutative and satisfy the same conjugation rule as the parent particle, 
while it is Lorentz-transformed like a tensor field. The propagator is point like 

< 0|T[A+.t-i*^i(pi), A.t"^^^^(p2)]|0 >= +^2)^7™/'^"^^ . (7) 

[zirjH 

Further information about the use of the Faddeev- Popov ghosts, Goldstone bosons and auxiliary 
tensor fields can be found in the manual. 

Although it is possible to implement a new model of particle interactions directly using the table 
definitions described here, for complicated models with a large number of particles, parameters and 
Feynman rules, it is a good idea to use an external program to generate the model files. In section 
19.31 we briefly describe available packages for model implementation. 



9. Tools for model implementation and model repository at HEPMDB 



9.1. The SLHAplus package 

The SLHAplus 33|] package included in CalcHEP supports the reading of SLHA formatted pa- 



rameter files. It also allows the diagonalization of mass matrices on the fly. In many models of 
elementary particles, there are significant loop corrections to particle masses. Several packages haij^e 
been creai^d which nmform theseJiipp calculations for MSSM-like models. For example, Isajet 50 



SoftSusy|29|, Spheno(30|, SuSpect[5l|, and NMSSMTools|3l| . An agreement has been formed to pass 



the input parametera_aniLthe calculated particles spectra and mixing matrices via text files in the 
special format SLHA 40|, |41|. Below is an example of a SLHA input file for the MSSM spectrum with 
input parameters at the GUT scale. 



Block MDDSEL 

1 1 
Block SMINPUTS 

5 4.23000000E+00 

6 1.73100000E+02 
Block MINPAR 

1 1.20000000E+02 

2 5.00000000E+02 

3 l.OOOOOOOOE+01 

4 1 

5 -3.50000000E+02 



# Select model 

# sugra 

# Standard Model inputs 

# inb(mb) SM MSbar 

# mtop(pole) 

# Input parameters 

# mO 

# ml/2 

# tanb 

# sign(mu) 

# AO 



CalcHEP can create this file by adding the following lines to the Constraints table 



open I openAppend("suspect2_lha. in") 
inputll aPrintFC'Block MDDSEL # Select model\n") 
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input 2 
inputs 
input 4 
inputs 
input 6 
input? 
inputs 
inputs 
input 10 
input 1 1 



aPrintFC 
aPrintFC 
aPrintFC 
aPrintFC 
aPrintFC 
aPrintFC 
aPrintFC 
aPrintFC 
aPrintFC 
aPrintFC 



BLOCK MINPAR 



1 1 

Block SMINPUTS 



1 y.E 

2 IE 

s y,E 

4 y.d 

5 y.E 



5 yE 

6 yE 



# SUGRAXn") 

# Standard Model inputs\n") 

# mbCmb) SM MSbar\n", MbMb) 

# mtCpole)\n" ,Mtp) 

# Input parcimeters\n" ) 

# mO\n" ,Mzero,Mhalf ) 

# ml/2\n", Mhalf) 

# tb\n",tb) 

# signCmu) \n" , Cint)sgn) 

# AO\n",AO) 



The aPrintF command is similar to the C printf family of functions. It's return value is the 
integer number of printed symbols and not used in the rest of the model. The instructions above 
generate the file suspect2_lha. in. On the next line, the user can enter the system instructions to 
launch SuSpect which reads the SLHA input file, calculates the spectrum and writes the results in 
the SLHA output file suspect2_lha. out. 

sys I System("°/os/suspect2.exe" , " . ") 

The second argument of the System command can be used to specify the path to SuSpect. The 
generated output file in the case of SuSpect is suspect2_lha. out and contains the information 
stored in BLOCKs. For instance 

BLOCK MASS # Mass Spectrum 

# PDG code mass particle 



1000022 2.05916966E+02 # ~chi_10 

1000023 3.89679950E+02 # ~chi_20 
BLOCK STOPMIX # Stop Mixing Matrix 

1 1 4.29327465E-01 # cosCtheta_t) 

1 2 9.03148896E-01 # sinCtheta_t) 

2 1 -9.03148896E-01 # -sinCtheta_t) 
2 2 4.29327465E-01 # cosCtheta_t) 

To read this file, the user can enter the following command in the Constraints table 
rd I slhaRead("suspect2_lha.out" ,0) 

The second argument of slhaRead specifies the kind of data to read. Generally, the second argument 
is mi + 2m2 + 4m4 + Smg where: 



25 

1000006 
2000006 



1 . 15987932E+02 
7.67852128E+02 
1.00613369E+03 



# h 

# ~t_l 

# ~t_2 



ml 0/1 keep new data / keep old data 

m2 0/1 ignore mistakes / stop if a mistake in the input file is encountered 

m4 0/1 read DECAY / don't read DECAY 

m8 0/1 read BLOCK / don't read BLOCK 
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To get the values of parameters after reading the slhaVal function can be used as in: 

Mstl I slhaVal(MASS,MZ, 1,1000006) t mass of stopl 

Mst2 I SlhaVal (MASS, MZ, 1,2000006) % mass of stop2 

Ztll I SlhaVal ("STOPmix",MZ, 2, 1,1) % stop mixing matrix 

Ztl2 I SlhaVal ("STOPmix",MZ, 2, 1,2) 

Zt21 I SlhaVal (" STOPmix " ,MZ, 2, 2,1) 

Zt22 I SlhaVal (" STOPmix " ,MZ, 2, 2, 2) 

where the first argument of slhaVal is the name of the BLOCK to read, the second argument is the 
scale (in this example the scale parameter is not specified in the BLOCK so this is not used), the 
third parameter fixes the number of parameters for each line of the BLOCK, and the parameters 
follow. 

A SLHA file also can contain information about particle widths and decays channels. If such 
information is read (m4=0), CalcHEP uses the values read from the SLHA file in place of an automatic 
calculation if the ! was used in the particle table. 

The SLHAplus package in CalcHEP is considered as a collection of tools for realization of Con- 
straints. Except of SLHA interface it contains routines for matrix diagonalizing adapted for direct 
implementation in CalcHEP tables. Using this part of SLHAplus one can diagonalize real symmet- 
ric matrices (for a multiplet of real scalar fields), complex hermitian matrices (for complex boson 
fields), generic complex matrices ( for spinor Dirac field^, and real matrices ( for spinor fields ). 
For example 

id I rDiagonal (d , Ml 1 , M12 , . . Mid , M22 , M23 . . . Mdd) 

diagonalizes a real symmetric matrix of dimension d. The d{d + l)/2 matrix elements, Mij {i < j), 
are given as arguments. The function returns an integer number id which serves as an identifier 
of the eigenvalue vectors and rotation matrix. Then MassArray (id, i) returns the eigenvalue rrii 
ordered according to their absolute values, and MixMatrix(id,i, j) returns the rotation matrix Rij 
where 

Mij = ^ RkirrikRkj 

k 

The SLHAplus package also supports an implementation of the QCD running couplings. It is 
initiated by the command 

LamQCD I initQCD(alphaSMZ, McMc, MbMb, MtPole) 



^For spinor field we can rotate independently the left and right components. So, two unitary rotation matrices are 
needed to diagonalize a generic fermion mass matrix. 
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where the input parameters are the running QCD couphng at MZ, the running masses for the c-, fe- 
at their own scales: Mc{Mc), Mb{Mb), and t— quark pole mass. The return value is Xqcd- After 
initialization, this will be used in the following functions alphaQCD(Q) to calculate the QCD coupling 
at any scale, McRun(Q), MbRun(Q), MtRun(Q), which calculate the running masses, and McEff (Q), 
MbEf f (Q) , MtEf f (Q) which calculate the quark masses for effective Yukawa couplings. These effective 
couplings take into account loop corrections for Higgs width calculations. The functions of Section 
19.21 also belong to the SLHAplus package. 



9.2. Effective Higgs 7-7 and glue-glue interactions 

The functions of this Section also belong to 
The SLHAplus package was updated for CalcHEP 
section. 



to include the functions presented in this 



Construction of effective vertices 

The interactions of the Higgs field with electrically charged and colored particles induce inter- 
actions with the gluon (h-glu-glu) and photon (/i-7-7) at loop order. These interactions lead to 
important contributions to the Higgs production and decay. The leading induced effective operators 



for these interactions can be written as 52, 53 



Mghss 
htpi'j^ip — )> 



a 



'4M2 



)/Ms 



IGtt 



(9) 
(10) 



where a is either the strong or electromagnetic coupling, is a color factor which depends on the 
color representation of the virtual particle. For a fundamental SU(3) representation, = 3 for 
photon vertices and = 1/2 for gluon vertices. For an adjoint representation, f'^ = 8 for a photon 
and = —2 for a gluon. q is the electric charge of the particle in the loop for the 77 operator and 1 
for the gluon operator. The functions A1/2, AiAq, A^j^ can be found in 53|. They are implemented in 
the SLHAplus package and have the names HggF , HggV, HggS, HggA, respectively. These functions 
return a complex value where the imaginary part appears if the argument is larger than one. 
In CalcHEP notation, the XhF y,y(^A)F^^ i^A) vertex is implemented as 



53 



PI |P2 |P3 |P4 |> Factor < I >dLagrangian/dA(pl)dA(p2)dA(p3) 
A I A |h I I -4*lainbda I (pi .p2*nil .m2-pl .m2*p2 .ml) 

whereas the TP-odd interaction XhFf^,y{A)Ff^'^{A) is written as 

A |A |h I I -4*lambda I eps (pi ,ml ,p2,m2) 

CalcHEP assumes that these vertices are self-conjugate, but in general, the hVV couplings are 
complex. However, we note that after squaring and summing over the diagrams, the result is the 
same as if we replace the complex coupling with its absolute value after summing all the amplitudes. 
That is, the complex couplings from all the effective operators should be summed. The value of 
lambda should be set equal to the absolute value of this sum. 

QCD corrections to /177 coupling 

There are important QCD corrections for the /177 effective vertex induced by colored particles in 
the loop. This correction can be described by an overall factor for the coupling 

where Mi is the mass of the loop particle. The Ci functions are known for vector, axial-vector, and 
scalar interactions if the loop particle has color dimension 3. The formulas are rather cumbersome 
and only have simple analytic forms in asymptotic limits. The SLHAplus package contains the 
HgamF(r) , HgamA(r) , HgaiiiS(r) complex functions which interpolate between tabulated data for 
the Ci functions for fermion loops with scalar interaction, fermion loops with pseudoscalar interac- 
tions, and scalar loops, respectively. The HDECAY package was used to generation the tables. The 
appropriate QCD scale for is Mh/2. It allows to effectively take into account large logarithmic 



corrections at higher order [52 . 



QCD corrections for hgg coupling 

The h — 7- GG process at NLO contains radiative corrections which are plagued by infrared 
divergences which cancel against infrared divergences in loop diagrams caused by virtual gluons 
attached to external legs. For this reason, QCD NLO corrections are presented for partial widths 
and cross sections, but not for effective vertices as in the h'j'j case. CalcHEP users have to implement 
these NLO factors to vertices in form 

H ^nlo 

TT 

where Fnio is the NLO contribution for the hGG partial width. 
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The QCD correction for the hGG interation induced by heavy quark loops are known at NNLO. 
In case of a scalar ([8]) and preudo-scalar (fTTj) interaction they are, respectively [54 
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T?11 
nlo 



/95 


7^ A 




VT 


6 J 





[ 370.20 - 47.19n/ + 0.9018nJ - ("^ + ^) log tt^ 



nlo 



221 
12" 



TT 



171.5 -5 log 



(13) 



(14) 



The last ex pre ssion is presented for Uf = 5. The quark masses in these expressions should be the 
pole values |56| and ag should be calculated at scale. The QCD corrections to the hgg vertex 
in case of a massive fermion loop when Mf ^ Mh/2 was calculated in 57| and appears to be at 
about the ~ 1% level. 

The NLO QCD corrections for effective vertices induced by loop of scalar color particle ( for 
instance SUSY squark) is known at NLO and appears to be a factor of 17/6 larger than F^f^ 58 



nlo y ^2 



7nf 
~6 
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Equations ( fT3l [HI ITSl) were obtained in the limit of Mf^g << Mh/2. However, it appears that 
they work well even beyond this limit. See an example of the implementation of the loop induced 
Higg boson vertices in the "SM(CKM=1 with hGG/AA)" model coming with CalcHEP. 

9.3. Packages for implementing new models 

There can be hundreds or thousands of Feynman rules to implement into CalcHEP for a given 
model. This can be a tedious and error prone process. For this reason, there have been several 
packages developed to take a Lagrangian, derive the Feynman rules and output them to the format 
of CalcHEP. The first of these was LanHEP 3J]. All of the default models that ship with CalcHEP (as 
well as many others) were generated using LanHEP. Recently, FeynRules 35| and SARAH 59| were 
created to do a similar job. Each package has its strengths. In this section, we will describe a very 
simple extension of the SM and describe its implementation into LanHEP and FeynRules. 



The model we will implement is called the Inert Doublet Model (IDM) (60|, l6l| . In this paper, we 
will only describe the new particles and interactions of this model. We begin with the SM and add 
to it a new SU{2) x f/(l) scalar doublet. In unitary gauge the SM Higgs and the new scalar doublet 
are given by 



Hi 







{v) + h/V2 



Ho 



(16) 



( iX + tH,)/V2) 

where Hi is the SM Higgs doublet and H2 is the new inert doublet which does not couple to quarks 
and leptons. Unlike the SM scalar doublet it does not develop a vacuum expectation value. H~^, 
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X, and are the new fields of tlie model. The IDM Lagrangian contains only even powers of the 
doublet H2 

C = CsM + D^H;D^H2-fil\H^\^ (17) 
-Asli/al' - Aali/iHi/al' - \4\hIH2\^ - \^Re[{HlH2f] 

Because of the H2 — )■ —H2 symmetry, the lightest new particle is stable. In the following example 
we will use the masses of the new particles as well as A2 and \l = (A3 + A4 + as independent 

parameters. The couplings yU, A3, A4, and A5 can be expressed in terms of the independent parameters. 

9.3.1. LanHEP 

The LanHEP package was the first package to automatically generate CalcHEP model files from 
a Lagrangian. It starts from a model definition in terms of particle multiplets and performs substi- 
tutions of physical particle fields from the multiplets. LanHEP also checks at the symbolic level for 
the absence of linear terms and at the numerical level for the absence of off-diagonal terms in the 
quadratic part of the Lagrangian. Also, LanHEP compares the diagonal quadratic terms with the 
declared particle masses. LanHEP allows to avoid a large number of mistakes which could appear in 
the derivation of Feynman rules by hand. The package and manual can be found at 

http : //theory . sinp . msu . ru/~semenov/lanhep . html 

The downloaded IhepiViViV.tgz file contains the source code as well as a set of examples. For our 
example, we present part of a LanHEP input file for the Inert Doublet Model. We describe only the 
new particles and new interactions beyond the Standard Model. 

The LanHEP source file for the IDM should contain a description of the new free parameters 

parameter MHX=111,MH3=222,MHC=333. t Declaration of new masses 
parameter laL=0.01, la2=0.01. % Declaration of new couplings 

and a declaration of the new constrained parameters 

yomu"2 as a function of masses 

parameter mu2=MHX**2-laL* (2*MW/EE*SW) **2 . 

°/o constraints for couplings 

parameter la3=2* (MHC**2-mu2) / (2*MW/EE*SW) **2 . 
parameter la5= (MHX**2-MH3**2) / (2*MW/EE*SW) **2 . 
parameter la4=2*laL-la3-la5 . 

The new particles of the model would be written as 
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scalar ' ~H3 V ~H3' : ( ' odd Higgs',pdg 36, mass MH3, width wH3 = auto), 
scalar ' ~H+ V ~H- Charged Higgs'.pdg 37, mass MHC, width wHC=auto) . 
scalar ' ~X' /' ~X' :(' second Higgs',pdg 35, mass MHX, width wHX=auto) . 

We use the component fields defined above to construct the second scalar doubet as 

let h2 = -[ -i*'~H+', ( ' ~X'+i* ' ~H3 ' )/Sqrt2 }, 
H2 = { i*'~H-', ('~X'-i*'~H3')/Sqrt2 }. 

Next, we define covariant derivatives for the new doublet where Bl is the SM U{1) gauge field 
and WW={W- ,W3 , W+} is a SM SU{2) triplet, gl and g are the corresponding couplings, taupm is the 
generator of the SU{2) group in the {W-,W3,W+} basis. 

let Dh2"mu"a = (deriv"mu+i*gl/2*Bl"mu) *h2~a + 

i*g/2*taupm"a"b"c*WW"mu"c*h2"b . 
let DH2"mu"a = (deriv~mu-i*gl/2*Bl"mu) *H2~a 

-i*g/2*taupm"a~b"c*{'W-' "mu,W3~mu, 'W+' "mu}~c*H2~b. 

The terms of the Lagrangian in Eq. f lT7|) can now be written in LanHEP notation as 

Iterm DH2*Dh2. % Kinematic and other terms. 

Iterm -mu2*h2*H2. 

Iterm -la2* (h2*H2) **2 . 

Iterm -la3*(hl*Hl)*(h2*H2) . 

Iterm -la4* (hl*H2) * (Hl*h2) . 

Iterm -la5/2* (hl*H2) **2 + AddHermConj . 

where hi and Hi are the SM Higgs doublet and its conjugate while h2 and H2 are the new doublet 
and its conjugate. 

Finally, compilation of the LanHEP source file to obtain the CalcHEP model files can be done 
with the command 

Ihep <source file> -ca -evl 2 
9.3.2. FeynRules 

FeynRules was originally developed to generate MadGraph model files from a Lagrangian in 
analogy to LanHEP for CalcHEP. However, it was soon decided that a package that could export to 
any code was desirable. For this reason, one of us (NC) became involved in the FeynRules project 
and wrote the CalcHEP export functionality for it. FeynRules has now become a mature package 
with many of its own features which support the implementation of new models beyond the SM. 
Further details and a manual can be found at the FeynRules website: 
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http : //f eynrules . irmp .ucl . ac .be/ 



FeynRules model files use Mathematica notation. We will now describe the analogous implementation 
of the IDM using FeynRules. 

The model implementation can reuse the SM file (SM.fr) which comes with FeynRules. To 
implement the other particles, parameters and Lagrangians, the user can open a new file in their 
text editor. Let's call it IDM.fr. The first thing to define are the parameters which are enclosed in 
an array named M$Parameters as in 

M$Parameters = { 



laL=={ 


ParameterType 


-> 


External , 






Value 


-> 


0.01 


}, 


la2=={ 


ParameterType 


-> 


External , 






Value 


-> 


0.01 


}, 


mu2=={ 


ParameterType 


-> 


Internal , 






Value 


-> 


MHX~2-laL* (2*MW/EE*sw) "2 , 






Description 


-> 


"mu~2 as a function of masses" 


}, 


la3=={ 


ParameterType 


-> 


Internal , 






Value 


-> 


2* (MHC"2-mu2) / (2*MW/EE*sw) ~2 , 






Description 


-> 


"constraints for couplings" 


>, 


la5=={ 


ParameterType 


-> 


Internal , 






Value 


-> 


(MHX"2-MH3"2) / (2*MW/EE*sw) ~2 


>, 


la4=={ 


ParameterType 


-> 


Internal , 






Value 


-> 


2*laL-la3-la5 


} 



>; 

where the independent parameters are given the property ParameterType->External and a numer- 
ical value while the dependent parameters are given the property ParameterType->Internal and an 
expression for the value. The new particles of the model would be enclosed in a M$ClassesDescription 
and written as 

M$ClassesDescription = { 
S[21] == { 

ClassName -> X, 

Self Conjugate -> True, 

Mass -> {MHX,111}, 

Width -> {wHX,0}, 

PDG -> 35, 

ParticleName -> "~X", 
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FullName 


-> 


"second Higgs" 


1 

n == { 






ClassName 


-> 


H3, 


Self Conjugate 


-> 


True , 


Mass 


-> 


{MH3,222}, 


Width 


-> 


{wH3,0}, 


PDG 


-> 


36, 


ParticleName 


-> 


"~H3" , 


FullName 


-> 


"odd Higgs" 



S[23] == { 



ClassName 


-> 


HC, 


Self Conj ugate 


-> 


False , 


Mass 


-> 


{MHC,333}, 


Width 


-> 


{wHC,0}, 


QuantumNumbers 


-> 


{q -> 1}, 


PDG 


-> 


37, 


ParticleName 


-> 


"~H+" , 


AntiParticleName 


-> 


"~H-" , 


FullName 


-> 


"Charged Hi 



S[24] == { 

ClassName -> h2, 

Unphysical -> True, 

Indices -> {Index [SU2D] } , 

Flavorlndex -> SU2D, 

Self Conjugate -> False, 

QuantumNumbers -> {Y -> 1/2}, 

Definitions -> { h2[l] -> -I HC, h2[2] -> (X + I H3)/Sqrt[2]} 

} 

}; 

where h2 is defined as the doublet which contains the component fields. The antiparticles are 
automatically defined the covariant derivatives in this simple example. 

The terms of the Lagrangian in Eq. (fT7|l can now be written in FeynRules notation as 

LIDMl = DC[h2bar[ii] , mu] DC[h2[ii], mu] ; 
LIDM2 = -mu2~2 h2bar[ii] h2[ii]; 
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LIDM3 = -la2 h2bar[ii] h2[ii] h2bar[jj] h2[jj]; 
LIDM4 = -la3 Phibar[ii] Phi[ii] h2bar[jj] h2[jj]; 
LIDM5 = -la4 h2bar[ii] Phi[ii] Phibar[jj] h2[jj]; 
LIDM6 = -la5/2 h2bar[ii] Phi[ii] h2bar[jj] Phi[jj]; 
LIDM7 = HC[LIDM6] ; 

LIDM = LIDMl + LIDM2 + LIDM3 + LIDM4 + LIDM5 + LIDM6 + LIDM7; 

where hi and HI are represented by Phi and Phibar while h2 and H2 are represeneted by h2 and 
h2bar. 

To compile the code and generate CalcHEP source code, the user must first load FeynRules as in 

$FeynRulesPath = "<FR path>"; 
SetDirectory [$FeynRulesPath] ; 
<< FeynRules ' ; 

where <FR path> is the path to the FeynRules package. Next, the user must load the model through 
the following command: 

SetDirectory [<1DM path>] ; 
LoadModel ["SM.fr" , "lDM.fr"] ; 

where <IDM path> is the location of the FeynRules files for the SM as well as the IDM file described 
here. After loading the model, there are many things that can be done with it in a Mathematica 
session such as checking the hermiticity of the Lagrangian, diagonalization of the quadratic terms, 
numerical values of the masses and so on. Further details can be found in the FeynRules manual. 
To generate CalcHEP model files, the user should finally run 

WriteCHOutput[LSM, LIDM] 

which will produce the CalcHEP files in the IDM directory. WriteCHOutput takes several options 
which are described in the FeynRules manual. 

9.3.3. SARAH 

SARAH is designed to work with SUSY models. Further details can be found at the SARAH 
website: 

http : / / sarah . hepf orge . org/ 
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9.4- HEPMDB model repository 

A convenient location to find and store CalcHEP model files is at the High Energy Physics Model 
Database (HEPMDB) Q which is located at 

http : / /hepmdb . soton . ac . uk/ 

HEPMDB is developing quickly and adding new features at a steady rate. A list of the models 
currently stored at HEPMDB along with their respective URL's can be found in Table El 

HEPMDB is not only a convenient repository for CalcHEP models. It is much more general and 
goes beyond CalcHEP, aiming to: 

1. collect HEP models for a large number of Matrix Element (ME) generators including CalcHEP, 
CompHEP dl, FeynArts B i], MadGraph/MadEvent [lol, [III, O, Q , AMEGIC ++/COMIX 



4. 



within SHERPA 17, 18 and WHIZARD 16 



2. store the source code for the models which users can download or use directly on HEPMDB 



to generate HEP models for various ME generators using the Fey n Rules [35| package or the 
LanHEP 3J] package. The source code consists of definitions for the particles, parameters and 
the Lagrangian in either FeynRules or LanHEP format. 

allow users to upload their models onto the HEPMDB server and use the High Performance 
Computing (HPC) cluster at Southampton University (IRIDIS3) to perform evaluations of HEP 
processes and generate events. The user does this through a web interface on HEPMDB which 
takes care of submitting the jobs and returning the results to the user. IRIDIS3 is currently the 
largest university owned HPC resource in the UK and gives the user of HEPMDB substantial 
computing resources for their calculation. Thus, HEPMDB provides a web interface to a large 
assortment of HEP models, a strong list of ME generators and a powerful HPC cluster to use 
them on. In this way, the user can bypass the difficulties involved in installing and setting up 
the various software and, instead, focus on the physics. 

cross check and validate new model implementations between different ME generators and 
different gauges. We should note that similar functionality is also provided by the FeynRules 
web validation 



28 



However, although the FeynRules web validation is more highly automated, 
it is focused on FeynRules models whereas the HEPMDB validation is designed to be more 
general and allow models implemented with any package to be validated. Also, it should be 
noted that the FeynRules web validation is only designed to perform validations. It does not 
have any capability to perform general physical processes or generate events, 
systematically collect the predictions and detailed features of the models included in the 
database. This will involve the development of a comprehensive database of signatures and the 
development of a format for the presentation of these features. The format for the signatures 
will be consistent with the format used by the experiments and HEPMDB wU perform a com- 
parison of the resulting predictions of the models with the experimental data. Further details 
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Model 


HEPMDB ID at 

http : //hepmdb . soton . ac . VLk/ID 


Standard Model (CKM=1) 


hepmdb: 1211 .0043 


Standard Model 


hepmdb: 1211 .0042 


Littlest Higgs Model with T-parity 


hepmdb: 06 11. 0024 


minimal B-L 


hepmdb: 06 11. 0030 


Minimal B-L with Higgs 1 loop vertices 


hepmdb: 06 11. 0031 


Minimal Zp models 


hepmdb: 1111 .0038 


MSSM 


hepmdb: 1211.0028 


NMSSM (from CalcHEP group) 


hepmdb: 1211.0046 


NMSSM with Flavor violation 


hepmdb: 1111 .0033 


NMSSM without Flavor violation 


hepmdb: 1111.0034 


BLE-SSM fminimal SUSY U(1)r x U(1)r - L 
model with inverse seesaw) 


hepmdb: 06 11. 0075 


SMSSM (most general, singlet extended MSSM) 


hepmdb: 06 11. 0074 


SUSY inverse seesaw (MSSM with additional 
singlet fields to incorporate inverse seesaw) 


hepmdb: 0612. 0073 


B-L-SSM (minimal, supersymmetric B-L model) 


hepmdb: 0612. 0072 


TNMSSM (Triplet extended NMSSM) 


hepmdb: 0612. 0072 


MSSM with bilinear R-Parity violation 


hepmdb: 1111.0036 


Model : RPV MSSM (FeynRules) 


hepmdb: 02 12. 0049 


RPV MSSM (LanHEP) 


hepmdb: 0312. 0060 


RPV MSSM (slha) 


hepmdb: 0512. 0068 


RPV MSSM (softsusy) 


hepmdb: 0512. 0070 


Model with 1st generation of the Leptoquarks 


hepmdb: 0612. 0076 


Model with 2nd generation of the Leptoquarks 


hepmdb: 0612. 0077 


Model with 3rd generation of the Leptoquarks 


hepmdb: 0612. 0078 



Table 2: Models and their unique links at HEPMDB 



28 under the title "Les Houches Recommendations 



can be found in the Les Houches report 
for the Presentation of LHC Results" activity. 
6. trace the history of the modifications of each model and make the full history available to the 
user. This feature will enable reproducibility for the results obtained from the models stored 
on HEPMDB. 
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10. Using CalcHEPas a matrix elements generator for other packages. 



In the previous sections, we have discussed the use of the CalcHEP generated code within 
CalcHEP. There are times, however, when a user would like to use the optimized squared ma- 
trix element code with an external package or with his/her own code. In the current version, a code 
has been included to allow new processes to be generated and linked dynamically. This code was 



first written for the micrOMEGAs|36l. l37l| package. In this section, we describe how to generate and 
use these dynamic libraries. 

To generate a squared matrix element for a given process dynamically, the user should write a 
main C program. An example of such program can be found at $CALCHEP/utile/main_22 . c. We 
have also included a shell script to compile the main program coUicting all the necessary libraries. 
It can be used as in the following example: 

$CALCHEP/bin/make_main main_22 . c 

where instead of main_22 . c> can be other main program written by the user. If compilation was 
successful, the program will be created and can be run. 

In the rest of this section, we describe the basic elements that are involved in writing a main 
program. It can be extended for more complicated cases. 

10.1. Set up 

At the beginning of the main file, the user should include all the required headers including the 
following CalcHEP headers: 

#include"num_in.h" 
#include"num_out .h" 
#include"VandP.h" 
#include"dynamic_cs .h" 
#include"rootDir .h" 

After beginning the main function, the user should define the following variables: 

REAL pvec [<4*nprts>] ; 
double GG; 
numout *cc; 

where <4*nprts> is 4 times the number of particles in the external states (nprts would be 4 for a 
2 — > 2 process). The array pvec contains the momenta of all the external particles. This must be 
filled by the user (or by the external program) for each phase space point. The user may find it 
helpful to define momenta for each individual particle as in the following 2 — )■ 2 example: 



63 



double *pl=pvec, *p2=pvec+4, *p3=pvec+8, *p4=pvec+12; 

where each of pi, p2, p3 and p4 are 4 dimenaional arrays holding the momentum of particles 1, 
2, 3 and 4 from the 2 — )■ 2 process. Each momenta contains the energy first followed by the 3 
dimensional momentum. So, for example, {Ei,pix,piy,piz) =(pl [0] ,pl [1] ,pl [2] ,pl [3] ). The 
variable GG should store the value of the strong coupling for the phase space point. The pointer 
cc will point to the dynamically generated code for the desired process. Multiple pointers could be 
defined if multiple processes are desired. 

10.2. Model choice 

The first thing the user must do is to choose the CalcHEP model he/she will work with. This is 
done with the setModel which has the following prototype 

int setModel (char* modelDir, int n) 

where modelDir is a string containing the path to the models directory and n is the model number for 
the model. For example, if the main program was being written in the WORK directory, this function 
call might look like setModel ("models" , 1) . The setModel command generates the aux subdirectory 
which is organised as a CalcHEP working directory with the subdirectories models, results, tmp 
and so_generated where the process libraries will be stored. It is very important to note that the 
model files in the aux directory will be copies of the ones from the WORK/models directory. After it has 
been created, any changes to the model in WORK/models will not affect those in aux and vice versa. 
The setModel function will also create the library VandP . so in the aux directory which contains 
a list of particles from the model as well as the compiled parameters of the model. If setModel is 
successful, it returns 0. 

It is possible to use multiple models in the same main function, but in this case, the aux directory 
will be cleaned and any libraries will be lost and have to be recreated. 

10.3. Model parameters 

Typically, the user would like to change the numerical value of the parameters, perhaps in a scan 
over parameters. There are three functions which can be used for this purpose. The prototypes for 
the first two are: 

int assignVal (char* name, double val) 
void assignValW(char* name, doube val) 

where name is a string containing the independent parameter name and val is the numerical value 
for that parameter. The only difference between these two functions is what happens when an error 
occurs. In the first case, a nonzero integer is returned while in the second case an error message is 
printed to stderr. 

Additionally, the new parameter values can be read from a text file with the following function 
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int readVar (char* fileName) 



where filename is the file that contains the new values. The file must contain two columns separated 
by whitespace. The first column must contain the name of the parameter while the second column 
must have the numerical value for that parameter. For example 

Mh 125 
MA 500 

where . . . represent further lines with other parameter values. readVar returns upon success. 
Otherwise, it returns a negative value when the file cannot be opened or a positive value corresponding 
with the line number in the file which cannot be read. 

After the independent parameters are assigned, the user must call the function 

int calcMainFunc(void) 

which calculates and updates all the public (see Section 18.21 for a definition of public) dependent 
parameters. This function returns when successful. If an error occurs, it returns a positive integer 
err which corresponds with the dependent parameter (varNames [err] ) where the error occurred. 

It is often useful to view the updated values of the parameters. For this reason, we include the 
following functions which work for any independent parameter or any public dependent parameter 

int f indVal (char* name, double* val) 
double f indValW(char* name) 

where name is a string with the name of the parameter. The first function, f indVal, sets *val equal 
to the numerical value of the paremeter and returns a nonzero value if it cannot find the parameter. 
The second function, f indValW simply returns the value of the parameter. It prints an error message 
to stderr if it cannot locate the parameter. 

At times, it will be necessary to access the parameters directly. They are stored in the following 
variables 

int nModelVars; 
int nModelFunc; 

char **varNames; // contains nModelVars+nModelFunc+1 elements. 

// varNames [0] is not used. 
REAL *varValues; // contains nModelVars+nModelFunc+1 elements. 

// varValues [0] is not used. 
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where nModelVars is the number of independent parameters in the model, nModelFunc is the number 
of public dependent parameters, varNames is an array of strings containing the parameter names, and 
varValues is an array containing the parameter values. It is important to note that both varNames 
and varValues have nModelVars+nModelFunc+1 elements. Both varNames [0] and varValues [0] 
are not used. The Type REAL is defined in the file $CALCHEP/include/nType.h. By default REAL 
corresponds with double. 

10.4. Model Particles 

The properties of the particles (see Section |3]) can be obtained with the functions in this section. 
The particle name can be obtained from the PDG code by using the function 

char* pdg2name(int nPDG) 

where nPDG is the PDG code. This function returns a string with the particle name upon success and 
NULL otherwise. On the other hand, the PDG code can be obtained from the name of the particle 
with the function 

int pNum(char * name) 

which takes the string name and returns the PDG code. However, if the particle name cannot be 
found, it returns 0. 

The quantum numbers of the particle can be obtained with the function 

int qNumbers (char* pName, int* spin2, int* chargeS, int* cdim) 

where the string pName should be the particle's name. The variable *spin2 will be filled with twice 
the spin of the particle, *charge3 will be filled with three times the electric charge of the particle, 
and *cdim will be filled with the color representation of the particle (either 1,3,-3 or 8). This 
function will return the PDG code of the particle upon success and otherwise. 
The numerical value of the mass of a particle is returned by the function 

double * pMass(char* pName) 

where the string pName is the name of the particle. 

If the particle properties have to accessed directly, the variables for this are 

int nModelParticles; 
ModelPrtclsStr *ModelPrtcls ; 

where nModelParticles is the number of particles in the model and the type ModelPrtclsStr is 
defined in $CALCHEP/include/VandP .h 
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10.5. Decay widths and branching fractions 

The calculation of particle widths, decay channels and branching fractions can be done with the 
function 

double pWidth(char* pName, txtList branchings) 

where pName is the name of the particle. This function returns the width of the particle and fills 
the variable branchings with the details of the decay channels. The type txtList is defined in 
the file $CALCHEP/c_sources/dynamic_me/include/dynamic_cs .h. The use of branchings will be 
described below. 

If the widths of the particles were read from a SLHA file before the calling pWidth, then the width 
from the SLHA file will immediately be returned. On the other hand, if the widths were not read 
from an SLHA file, CalcHEP will calculate them in the following way. CalcHEP will first calculate 
the partial widths from all kinematically open 1 — )■ 2 decays channels. If the resulting width is zero 
at this point, it calculates the partial widths from all kinematically open 1 — 3 decay channels. If 
the width is still zero, it tries the 1 — >■ 4 decay channels. If the width is still zero, it returns zero for 
the particle's width. Otherwise, it returns the calculated width. An improved algorithm taking into 
account important off-shell contributions is planned for a future release. 

Once the decay widths and branching ratios are calculated, they can be printed to file using the 
function 

void print TxtList (txtList branchings, FILE* f) 

where branchings is the same variable used in the function pWidth and f is the file handle which 
has already been opened for writing. 

The branching ratio for a specific final state can also be obtained using the function 

doouble findBr (txtList branchings , char* pattern) 

where branchings is the same variable used in the function pWidth and the string pattern should 
be a comma separated list of the (anti)particle names in the final state. The order is not important. 
findBr returns the branching ratio for the requested final state. 

An alternate function that calculates the width and branching ratios is 

int slhaDecayPrint (char* pname, FILE* FD) 

where pname is the name of the particle and FD is the open file handle where the width and full list 
of branchings will be written in SLHA format. The return value is the PDG code of the particle if 
successful and zero otherwise. 
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10.6. Processes 

CalcHEP contains facilities to dynamically generate and link the code for any collision or decay 
process. This is done with the function 

numout* getMEcode(int twidth, int UG, char* Process, char* excludeVirtual , 

char* excludeOut, char* libName) 

where 

twidth is a flag which determines whether the t-channel propagators contain the particle width. 

UG is a flag which forces Unitary Gauge calculations whatever gage was initially specified in the 
model. 

Process is a string which contains the desired process. 

excludeVirtual is a string containing a comma separated list of particles to remove from the internal 
lines of diagrams. 

excludeOut is a string containing a comma separated list of particles to remove from the final state 
particles. This is useful when the process string contains "2*x" . 

libName is a string containing the name of the library where the compiled code will be stored. This 
name should not contain the ".so" suffix. 

If the library already exists, it will be dynamically linked and a pointer to the code of type numout 
will be returned. Note that if the library exists, it will not be checked whether it contains the same 
process. The user must take care with the names of the libraries and ensure they are correctly used. 
If the library cannot be found, it will attempt to dynamically generate and compile the code. If 
successful, it will store it in the file aux/so-generated/libName . so where libName is the string 
given to getMEcode. It will then dynamically link it and return the pointer to the code. Since 
the string libName is used for the name of the file, it cannot contain any characters not allowed 
in file names. For example, the special characters +, -, *, or / are not allowed. If the code 
cannot be generated and compiled successfully, NULL is returned. This could occur, for example, 
if the process is not allowed in the model. The structure of the type numout can be found in 
$CALCHEP/c_sources/dynamic_me/include/dynamic_cs.h. We will not explain this structure but 
give some examples of it usage. 

At this point, the parameters stored in dynamically generated process code are not related to the 
parameter values described above in Section 110.31 Before we use the dynamically linked code, it is 
very important to export numerical values of parameters. This can be done by running the following 
loop 
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f or(i=l ; i<=cc->interf ace->nvar ; i++) 

if (cc->link [i] ) cc->interf ace->va [i] =* (cc->link [i] ) ; 

where cc is a pointer of type numout obtained from the function getMEcode. It is important to note 
that this loop must be rerun every time the model parameters are changed. 

Further information about the processes in the dynamically linked library can be obtained with 
the functions 

int proclnfol (numout* cc, int* nproc, int* nin, int* nout) 

int procInfo2 (numout* cc, int nsub, char** pName, REAL* Masses) 

where cc is a pointer to the dynamically linked code from the function getMEcode. Both of these 
functions return zero if successful. In the first function, *nproc is filled with the number of subpro- 
cesses in the library, *nin is filled with the number of ingoing particles, and *nout is filled with the 
number of outgoing particles. In the second function, nsub specifies which subprocess the user would 
like information about, pName is an array of strings which is filled with the names of the ingoing 
and outgoing particles, and Masses is an array containing the masses of the ingoing and outgoing 
particles. Both pNames and Masses are arrays of size nin+nout. The ingoing particles are listed first 
with the outgoing particles following. 

10.7. Matrix elements 

After all the parameters are set and the code is generated and linked, the matrix element can 
be obtained. To do this, the user has to first fill the momentum array for the phase space point of 
interest. We defined the array pvect in Section [10.11 and assume the user has filled it with the phase 
space momenta. We also assume the user has already filled the variable GG with the value of the 
strong coupling constant at this phase space point. The matrix element can be obtained with the 
function 

double sqme(int nsub, double GG, REAL* pvect, int* err_code) 
which belongs to numout*cc structure returned by getMEcode 
cc->interf ace->sqme 

Here nsub determines which subprocess to use and *err_code is an integer which will contain the 
error code if any or zero otherwise. The return value is the matrix element at this phase space point. 
An example of using this function with the code given by cc is where cc is the pointer obtained from 
getMEcode. It should be noted that the polarizations of ingoing particles have already been summed 

over and the polarizations of outgoing particles have already been averaged in the result. 

Compilation of main_22 . c should create executable main_22. It has to be launched in user's 
$WORK directory. It compiles e,E->m,M and A,A->m,M reactions and calculates cross section for 
e,E->m,M at Pcm=100GeV. The screen output should be 
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PROCESS: e,E->m,M 
PROCESS: A,A->m,M 
EE=3.123000E-01 
SW=4.830000E-01 
Mm=1.057000E-01 
MZ=9. 118840E+01 
wZ=2 . 494440E+00 
CW=8.756204E-01 
sigmaTot=2 . 946325E+00 



11. Batch file examples with results 

In this section we present some examples of calculations using the batch interface (see Section [7j). 
We give the full details of the input and the output so users can test their installation. Users can 
also use these examples as templates for their own calculations. We assume in this section that the 
user has already installed CalcHEP and has already created a WORK directory. 

11.1. e+e" ^ Zh 

Our first example is for the process e^e'^ Zh. The batch file for this example comes with 
CalcHEP and can be found at $CALCHEP/utile/batch_f ile_l. It has the following form: 



Model: Standard Model 

Model changed: False 

Gauge : Feynman 

Process: e,E->Z,tL 

pdfl: ISR & Beamstrahlung 

pdf2: ISR & Beeunstrahlung 

Bunch x+y sizes (nm) : 560 

Bunch length (mm) : 0.4 

Number of particles : 2E+10 

pi: 500 

p2: 500 

Parameter: Mh=125 

Dist parameter: El 

Dist min: 

Dist max: 600 

Dist n bins: 100 

Dist title: p,p->Z,h 

Dist x-title: El (GeV) 

Number of events (per run step) : 10000 

Filename: ee_zh 

Max number of cpus : 2 

nSess_l: 5 

nCalls_l: 100000 

nSess_2: 5 

nCalls_2: 100000 

This batch example can be run with the following command (from the WORK directory) 
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. /calchep_batch batch_file_l 

It will calculate the cross section of the process e~^e~ Zh at ^/s = 1 TeV taking into account ISR 
& Beamstrahlung effects using the beam geometry specified in the batch file. This batch will also 
generate lOK events and write them in the file ee_zh-single . Ihe located in the $WORK/Events/ 
directory in LHEF format. The total cross section of this process is 16.9 fb. The result of this batch 
session can be observed in a web browser as in Fig. HJ 



Home 

Symbolic Results 
Numerical Results 
Events Library 
Process Library 
Help 

Thank you for 
using CalcHEP! 



Numerical Sessions 

standard Model 

Done! 

Processes a (fb) Ao (%) PID Time (hr) N events Details 

e,E->Z,li 16.934 0.012 30517 0,00 10500/10500 prt 1 session.dat 

Total 16.934 



Decays r (GeV) 4r (%) PID Time (hr) N events 



Details 



Widtlis 

Widths 



PID Time (hr) 

30537 0.00 



Details 

session.dat 



Total 16.93 



0.00 10000/10000 

Distributions 



P,P->?,h 



3QB 
El (Gov) 



Figure 4: Results of the batchjEile_l evaluation. 
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11.2. e+e — hfi^fi — )■ yU+yU bb with only e+e — )■ Zh diagram 

In this example, we will evaluate the process e~^e~ — ?■ hfi^fi" — > fi'^f-i^bb and remove the diagrams 
that do not correspond to e~^e~ — )■ Zh. Our batch file can be found at $CALCHEP/utile/batch_f ile_2 
and has the following form: 

Model: Standard Model 

Model changed: False 
Gauge : Feynman 
Process: e,E->m,M,h 
Decay: h-> b,B 

Remove: A,e,in 
pdfl: ISR & Beamstrahlung 

pdf2: ISR & Beeunstrahlung 

Bunch x+y sizes (nm) : 560 
Bunch length (mm) : 0.4 
Number of particles : 2E+10 
pi: 500 
p2: 500 
Parameter: Mh=125 
Regularization momentum: 34 
Regularization mass : MZ 
Regularization width: wZ 
Regularization power: 2 
Dist paraimeter: M(m,M) 
Dist min: 
Dist max: 120 
Dist n bins: 100 
Dist title: p,p->m,M,h 

Dist x-title: M(m,M) (GeV) 

Number of events (per run step) : 10000 

Filename: ee _mmh_mmbb 

nSess_l: 5 

nCalls_l: 100000 

nSess_2: 5 

nCalls_2: 100000 

One should note three new elements in this batch as compared to the previous one: 

1. Decay: this statement generates Higgs boson decay which is automatically connected to the 
production mode; 

2. Remove: this statement specifies that diagrams with internal photons, electrons or muons should 
be removed (that is, only the e'^e~ — )■ Zh process is kept). 

3. Regularization: this statement is used to perform a more efficient integration of the Z-boson 
resonance peak. 



By running 

. /calchep_batch batch_file_2 

the batch interface will calculate the cross section, generate lOK events with a fi~^fi~bb final state 
written in the ee_nimh_nimbb-single . Ihe file. The total cross section of this process is 0.517 fb. 
Again, the user can check the results in his/her web browser which should agree with Fig. [51 
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Home 

Symbolic Results 
Numerical Results 
Events Library 
Process Library 
Help 

Thank you for 
using CalcHEPl 



Numerical Sessions 

standard Model 

Done! 



Processes o (fb) Aa (%) PID 



Time 
(hr) 

e,E->h,m,M 0.56663 0.074 31593 0.00 
Total 0.56663 



N events Details 

10500/10500 prt l session.dat 



Decays F (GeV) AF (%) PID 

li->b,B 0.0026022 4.5 

xlO 



Time 
(hr) 

31613 0.00 



n,-05 



N events Details 

50998/51000 prt_l session.dat 



Widths 

Widths 



PID 



Time 
(lir) 

31633 0.00 



Details 

session.dat 



Total 



0.5169 



0.00 10000/10000 

Distributions 



a, 12 



p,p->n,H,h 



5 B.flG 



4B ea 

Mh,»> (GeV) 



Figure 5: Results of the batch_f ile_2 evaluation. 
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11.3. pp^Wbb^eubb 

In this example, we consider the process pp Wbb 
$CALCHEP/utile/batch_f ile_3 and has the following form: 



?z/66. The batch file can be found at 



Model: Standard Model (CKM=1) 

Model changed: False 



Gauge : 
Process : 
Decay : 
Composite 
Composite 
Composite 
Composite 
Composite 
pdf 1: 
pdf2: 
pi: 
p2: 

Run parameter: 
Run begin: 
Run step size: 
Run n steps : 
alpha Q : 
Cut parameter: 
Cut invert : 
Cut min: 
Cut max : 
Cut parameter: 
Cut invert : 
Cut min: 
Cut max : 
Cut parameter: 
Cut invert : 
Cut min: 
Cut max : 
Kinematics : 



Feynman 
p,p->W,b,B 
W->le,n 

p=u,U,d,D,s,S,c,C,b,B,G 

w=w+,w- 

le=e ,E,m,M 
n=ne , Ne , nm , Nm 
jet=u,U,d,D,s,S,c,C,b,B,G 
cteqSl (proton) 
cteq61 (proton) 
4000 
4000 

Mh 
120 
5 
3 

M45 
M(b,B) 
False 
100 

J(jet , jet) 
False 
0.5 

T(jet) 
False 
20 



12 -> 3, 
45 -> 4 



45 
5 



Kinematics : 
Regularization momentum: 45 
Regularization mass: Mh 
Regularization width: wh 
Regularization power: 2 

Dist pareimeter: M(b,B) 

Dist min: 100 

Dist max: 200 

Dist n bins: 100 

Dist title: p,p->W,b,B 

Dist x-title: M(b,B) (GeV) 

Dist parameter: M(W,jet) 

Dist min: 100 

Dist max: 200 

Dist n bins: 100 

Dist title: p,p->W,b,B 

Dist x-title: M(W,jet) (GeV) 

Number of events (per run step) : 10000 

Filename : pp_Wbb_enbb 

nSess_l: 5 

nCalls_l: 100000 

nSess_2: 5 

nCalls_2: 100000 
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A new feature of this batch file is that it performs a scan of pp — )■ Wbb — ?■ iubb as a function of 
the Higgs boson mass using the Run parameter statement. The result of this scan can be seen on a 
web browser as shown in Fig. [6l 



Numerical Sessions 

standard Model(CKM=l) 

Done! 

Scaus a (fb> Ruuuing Finished Time (hr) N events 

Mh=120 1261 0/13 13/13 0.01 10000 

Mh=125 1251 0/13 13/13 0.01 10000 

Mh=130 1244 0/13 13/13 0.01 10000 

0.03 

Figure 6: Results of the batchj£ile_3 evaluation. 

Further details on the individual numerical sessions can be checked by clicking on a particular 
value of the running parameter. For example, clicking on Mh=125 in the web browser will lead to the 
html page shown in FigH This page also presents the requested distributions. 

We would like to note that all the results shown in the html browser are also recorded in the pure 
text files located in the $WORK/htnil directory. For example, the results for the numerical session are 
recorded in the file $WORK/html/numerical .txt as well as in the files in the $WORK/htinl/runs direc- 
tory which contain further details. For example, after a successful run of the file batch_f ile_3 given 
in the example above, the user should get the file $WORK/htnil/numerical .txt with the following 
lines: 

CalcHEP Numerical Details 
Done ! 

Scans sigma (fb) 

Mhl20 1.2610e+03 
Mhl25 1.2510e+03 
MhiaO 1.2440e+03 
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Figure 7: Details of the numerical session for pp Wbb — >■ iiybb for Alh = 125 GeV for the batchjf ile_3 file evaluation 
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12. Conclusions and outlook 

The new version of CalcHEP, version 3.4 presented here is ready to explore the Standard Model 
and BSM models by theorists, phenomenologists and experimentalists. CalcHEP can be used: 

1) via an interactive GUI interface which allows to understand the anatomy of the process under 
study including details of the interference; 

2) via a batch interface which highly automatizes and parallelizes the evaluation of numerous pro- 
duction and decay processes as well as conencting them together at the stage of event generaton; 

3) through the High Energy Physics Model Database (HEPMDB) using the resources of a powerful 
HPC cluster which allowes to perform an exaustive scan of the model parameter space and generate 
numerous LHE files in one run. 

We should also stress that there are many BSM models available for CalcHEPat the HEPMDB 
site and it is easy to implement new models by means of the LanHEP and FeynRules packages. 
The next development of CalcHEP will include 

1) an implementation of an automatic regularisation procedure. 

2) an implemention of projections on polarization states of the massive fermions and vector bosons 

3) taking into account spin correlatons for the processes when connecting production and decays. 

4) an implementation of the jet matching procedure which will allow to properly combine subprocess 
with multi-jet final states. 

5) an implementation of the helicity amplitude method which allows to evaluate processes with larger 
final state particles multiplicity as well as spin correlation when connecting production and decay 
processes. 

6) a new improved interactive numerical session which sums over the subprocesses and connects 
production and decay processes in the GUI as well as parallelizing over multiple cpus on a multicore 
machine. 

Work in all these directions is in progress. The CalcHEP team is open to additional sugegstions/requests 
from users. 
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